How to design better APIs
· 7 min read
- Be consistent
- Use ISO 8601 UTC dates
- Make an exception for public endpoints
- Provide a health check endpoint
- Version the API
- Accept API key authentication
- Use reasonable HTTP status codes
- Use reasonable HTTP methods
- Use self-explanatory, simple names
- Use standardized error responses
- Return created resources upon POST
- Prefer PATCH over PUT
- Be as specific as possible
- Use pagination
- Allow expanding resources
APIs are awesome, but they're also extremely hard to design. When creating an API from scratch, you need to get many details right. From basic security considerations to using the right HTTP methods, implementing authentication, deciding which requests and responses you should accept and return, ... the list goes on.
In this post, I'm trying my best to compress everything I know about what makes a good API. An API, that your consumers will enjoy using. All tips are language-agnostic, so they apply to any framework or technology.