API Design : How to get it (almost) right
API is the developer interface to your service. Get it right and you will have happy developers developing amazing stuff with your help. Get it wrong and everyone using it will hate the design and expect a lot of support queries. Once an API is public, it is permanent. If you want to fix it, you have to release a new version of the API. Now that you see why API Design is super important. Let us see what we can do to get it as (almost) right.
Keep it small and simple
- The initial spec should be as small as possible, not smaller. Remember, adding stuff is easy, removing is not.
- Write the documentation of the endpoints and their purpose before writing code helps in saving time wasted in implementing useless endpoints
- Be consistent in naming and definitions
Version your API carefully
- Mistakes will be made and at some point, you need to release a new version of the API
- API should support versioning from day 0, It is much better to have
/v1/productsthan to have
/productsin v1 and
Always use Nouns instead of Verbs
- Always have
/productas a get request instead of having
/getProducts. Which brings us to the next point
Extensively use the HTTP methods available
Read and refer : HTTP request methods
Here is the gist
GET : Get a resource or a collection of resources POST : Insert a resource or a collection of resources PATCH : Update a resource or a collection of resources DELETE: Delete a resource or a collection of resources
Make use of get parameters
- Let the user of the API decide what he/she wants to get, better to have /product?name=book then /getProductByName
- Make sure to document all the parameters, and have sane default values for the parameters if needed
Extensively use HTTP codes
- Read and refer : HTTP response status codes
- It is always much easier to check for status code and do something than to parse some data structure and do a string match to figure out what should be done.
- You still have a lot of status codes at your disposal. Make sure you carefully utilize them and again, Document all things!
Support common operations like Pagination, Sorting, Filter, and Search
- If you have a get call to some resource and it returns a decently sized data points. Chances are the client wants some flexibility.
- The API should natively support some common operations like pagination, sorting, filtering and search so that the client can stay clean and a lot of the work can be offloaded to the database.
- Pagination will also reduce the data sent over the wire, it only sends what is required.
Use the Open API Specification
Sharing an open API file means a lot to developers since they can see how exactly a request must be made, and what can be expected back. API Resources | Swagger
Tools like prism can be used to mock the entire server from the open API file so that development can be a breeze stoplightio/prism
Error codes are better than error responses
- If HTTP status codes are not communicating enough back to the client. Have a list of predefined status code list with the a default description which will be included in the error response. From a client stand point, it will be much easier to look at the error code than looking at the error response
- The server must also send out an error message along with error code which can be used as a safe fallback in case the error code is not sufficient.
This is a living document and will be updated based on things I have learned over time