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
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.
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).
“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: