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.
