Creating a Readable REST API

DZone 's Guide to

Creating a Readable REST API

In this article, take a look at some tips on how to create a readable REST API.

· Integration Zone ·
Free Resource

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, etc., so 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 API for developers to consume. It’s a more subtle and less-discussed topic that can have a significant impact on the success of your API. After all, an API that no one can read, no one will use.

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. 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 introduce changes to an existing method (omission, bug, functionality change), consider creating an alternative 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 fetch specific data to maintaining a limited amount of methods so the developer can easily have a mental model of the API and grasp it quickly. 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 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 param is missing or has an invalid value instead of a general, “Missing required param/invalid input” message.

That’s all for now. Leave me a comment if I’ve forgotten anything.


api, backend, documentation, jwt authentication, rest

Published at DZone with permission of Alexander Fo . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}