Simple Practices for Designing RESTful API


Following these standards means:

  • Documentation will make more sense and so developers will understand your API quicker.
  • Developers will therefore be able to integrate quicker and therefore deliver products faster and at lower cost.
  • Many of the principles will make your clients faster, improving product quality

1. Use nouns but not verb

For an easy understanding use this structure for every resources:
Screenshot from 2016-04-06 01:11:33

Note: Do not mix up singular and plural nouns, Keep it simple and use only plural nouns for all resources

2. Use sub-resources for relations

If a resource is related to another resource use subresources
Example: GET /cars/711/drivers/4  Return driver #4 for car 711

3. Provide filtering, sorting and paging for collections


Use a unique query parameter for all fields.
Example: GET /cars?color=red


Allow ascending and descending sorting over multiple fields.
Example: GET /cars?sort=-model


Use limit and next URL. It is easy for the client to showing items.
Example: /cars?limit=10


4. Version your API

Make the API Version mandatory and do not release an unversioned API.
Note: Use a simple ordinal number and avoid dot notation such as 2.5

5. Error handling

Error responses should include a common HTTP status code, message for developer, message for the end-user (when appropriate).
For example:

“developerMessage”:”Verbose, plain language description of the problem”,
“userMessage”:”This is a message that can be passed along to end-users, if needed.”

Use three simple, common response codes indicating (1) success, (2) failure due to client-side problem, (3) failure due to server-side problem:

  1. 200 – OK
  2. 400 – Bad Request
  3. 500 – Internal Server Error

6. Using actions

Sometimes, it is required to expose an operation in the API that inherently is non RESTful. Actions are basically RPC-like messages to a resource to perform a certain operation.

Example: POST /users/12/follow   Following user #12

Note: The actions should only be used as an exception, when there is a good reason that an operation cannot be mapped to one of the standard RESTful methods.

Thank you guys: