When you are creating a RESTful API, it’s easy to get overwhelmed by all the different things you need to take into consideration. Throttling, REST verbs, security, authentication, input validation and etc. It’s easy to forget about the more subtle issues that can make a lot of difference in the long run. Most of the topics described above were already discussed (extensively if not exhaustively) elsewhere, so I’ll try to give my take on how to create a readable REST API for developers to consume. It’s a more subtle and less discussed topic which can have a significant impact on the success of your API. After all – an API that no one can read no one will use:
Rules of thumb
Use a convention for endpoint URLs and method names: plural vs singular – pick one. There is nothing worse than trying to fetch information from /api/v1/orders/{id} and debugging this forever just to find out that this is the only place where you have chose to use /api/v1/order/{id} (singular instead of plural) as the endpoint URL.
Don’t create API versions without a good reason to do this. V2 of the API should be a *significant* change over the original version (new methods, changed URL endpoints, different auth mechanism – etc). If you need to to introduce changes to an existing method (omission, bug, functionality change) consider creating a new method. Usually it’s better than bumping the version number.
Find the sweet spot between creating a lot of methods to provide with maximum flexibility for the developer to maintaining a limited amount of methods so the developer can easily have a mental model of the API. The more methods you have – the less parsing the developer should do on his end to fetch specific info. The less you have – the easier it is to understand the API.
Find the sweet spot between providing verbatim output (for instance all lead data when you fetch for a list of leads) and minimizing the number of developer calls to the API (no need to fetch the the lead id and call the lead endpoint to get details for the specific lead) to making the API responses small in size and intuitive. Note that this is less of a concern if you have a GraphQL API in which you can query the API for specific data.
Stick to conventions in REST verbs. If you use PUT to create a new instance of an entity – make all methods use PUT to create an instance and POST/PATCH to edit it and visa versa.
Use Swagger to document the API. It has become somewhat of an industry standard and it improves readability 10 fold.
Provide examples for each method – this can make a lot of a difference for a developer struggling with your API
Stick to a convention in your error response object and provide meaningful exception messages with proper error codes. Hint: “an error has occured” is not a good error message. Likewise, it’s better to tell the developer what input parameters are missing or have invalid value instead of a general: “Missing required param/invalid input” message.
Summary
Creating a readable REST API is something that is not considered “sexy” or most important part of your API but in the long run it can have major impact on the way (and if) your API is used.
That’s all for now. Leave me a comment or drop me a line if I’ve forgot anything.
Cheers