Versioning
/api/v1/resource_name
Deprecated
Should return 410 Gone
HTTP Status Code to indicate that the new endpoint is not supported and should not redirect
- Alternatively, if a new API endpoint is backwards-compatible, you can redirect to the new endpoint
/api/v2.2/customers/1234 >>> /api/customers/1234
/api/v2.0/customers/1234
/api/v2/customers/1234
/api/v1.1/customers/1234
/api/v1/customers/1234
Simple is better
api/products/12345
- Easy to learn/use
- hard to misuse
- fails fast
- good names (self-explanatory)
- split into modules
- when in doubt, leave it out (easy to add, hard to remove)
- maximize info hiding. don't let info leaks in logs/exceptions
- minimize coupling between APIs
- document as many details as possible
- keep performance in mind while designing API
- It is always good practice to keep backward compatibility so the customers can get enough time to move to the next version when the API version changes
- Pagination
- Use of pagination is a must when you expose an API which might return huge data and if proper load balancing is not done
- Without pagination, one customer might end up bringing down the entire service
- Proper Error Message
- Always good practice to keep set of error messages application sends and responds with proper corresponding id
- Alternative is to return a URL with error message which tells you more about the error message and how to handle it as well
// facebook's API Error messages
{
"error": {
"message": "(#803) Some of the aliases you requested do not exist: products",
"type": "OAuthException",
"code": 803,
"fbtrace_id": "FOXX2AhLh80"
}
}
Return Format
Most of modern day APIs should return JSON response
- Open API standard allows you to design your APIs first and share that with the consumer in an easy manner
- https://swagger.io/resources/open-api/
Bulk API Operation
Use POST
or PATCH
with list payload
POST /group/users
[
{ "id": "userId1", "sequence": "newSequenceNumber1" },
{ "id": "userId2", "sequence": "newSequenceNumber2" },
(...)
]