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:
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:
- 200 – OK
- 400 – Bad Request
- 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/
