Simple Practices for Designing RESTful API

RESTful-Area

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

Filtering:

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

Sorting:

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

Pagination

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

Response:
{
items:[…],
nextURL:”…”
}

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:

{
“status”:400,
“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:

https://github.com/WhiteHouse/api-standards
http://mark-kirby.co.uk/2013/creating-a-true-rest-api/#comments
http://restful-api-design.readthedocs.org/en/latest/methods.html
http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s