Guideline/Checklist/Best pratice on API Design
Opened this issue · 2 comments
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 prefixcus_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/
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.
Also add an example for our best practice cloudwatch devops