Guideline/Checklist/Best pratice on API Design

[hendriknielaender]

In the wild you find a lot of post about API design and best practice. But a more comprehend guide, which is not too long. You can't really find.

Quick examples like: api/customers/:id/

• do not use integer ids (guessable)
• go with something like UUID, but with prefix cus_23lksjdg3 https://github.com/jetpack-io/typeid

endpoints:

• avoid nesting that is more than 3 levels deep posts/:id/comments

documentation:

• open api specs

errors: https://apisyouwonthate.com/blog/useful-api-errors-for-rest-graphql-and-grpc/

versioning: implement versioning with rolling versions that are named with the date they’re released (for example, 2017-05-24). Although backwards-incompatible, each one contains a small set of changes that make incremental upgrades relatively easy so that integrations can stay current.

Performance:

• gzip
• pagination, filtering, sorting
• caching
• rate limit & throttling

ai: https://apisyouwonthate.com/blog/ai-powered-api-linting-with-optic/

[hendriknielaender]

From Mediocre to Magnificent: Crafting Stellar APIs

Ready to turn your API from "meh" to "wow"? You're in the right spot. Today, we're diving deep into the world of APIs. Not just any APIs, but those that stand out.

🚀 Unique Identifiers: Beyond the Numbers

Forget the predictable numeric IDs; it's time to embrace the unique and the secure. Imagine an identifier that not only says "I'm unique" but also "Good luck guessing me!"

• Avoid Predictable IDs: Instead of integer IDs (/api/customers/123), opt for unpredictable, non-sequential identifiers like UUIDs. Enhance readability and security by adding a prefix, e.g., cus_23lksjdg3.
• Tool Recommendation: Explore typeid for generating type-safe IDs.
• A clear type prefix (like user for user IDs), making it obvious what the ID points to.
• Optimized for Databases: These IDs are K-sortable, meaning they play nice with your database's indexing and ensure quick, efficient data retrieval.

🔗 Endpoint Design: The Art of Simplicity

In the labyrinth of APIs, simplicity reigns supreme. We advocate for clarity and ease, ensuring your endpoints are as intuitive as a map to treasure.

• Golden Rule: If your endpoint resembles a nesting doll, you've gone too deep. Keep it shallow, keep it neat. /posts/:id/comments should be your complexity ceiling.
• RESTful Mastery: Embrace the elegance of RESTful principles, crafting endpoints that are not just paths but well-thought-out journeys for your data.

📚 Documentation: The Story of Your API

A great API without documentation is like a library without books. OpenAPI specs turn your API into an open book, inviting developers to read, understand, and integrate effortlessly.

❌ Error Handling: Turning Bumps into Jumps

Mistakes happen, but it's the recovery that counts. Transform errors from stumbling blocks into stepping stones with clear, constructive messages.

• Pro Tip: Dive into Useful API Errors to master the art of informative error reporting.

🕰️ Versioning: Keeping Time on Your Side

In the world of APIs, time is a canvas, and versioning is your paint. Date-based versions (like 2017-05-24) tell a story of growth and evolution, inviting users to journey through time with your API.

⚡ Performance: The Need for Speed

In the race of digital interaction, speed is king, and efficiency is queen. Embrace GZIP, wield the power of pagination, and let caching be your shield against the dragons of latency.

🤖 AI Integration: The Future is Now

Why merely lint when you can AI-lint? Step into the future with AI-powered tools like Optic, ensuring your API design isn't just good; it's futuristic.

---

Transforming your API from mediocre to magnificent isn't just about following best practices; it's about embracing a mindset of continuous innovation and user-centric design.

[flyck]

Also add an example for our best practice cloudwatch devops