- 1. Use Nouns but no Verbs
- Ex: /cars, /cars/23 ... Correct
/getCarData, /get/car/data ... wrong
- GET method & query parameter should not alter the state use PUT, POST and DELETE for changing the state
- 3. Do not mix up singular and plural nouns use only plural nouns
Ex: /cars instead of /car
- 4. Use sub resources for relations.
Ex: /cars/33/driver-> give details of driver of car ID 33
- Use headers for serialization. Content-type, Accept etc
- Pass hyoperlink in response for a better nevigation
- 7. Provide filtering, sorting, field selection and paging for collections
- Ex: GET /cars?color=red Returns a list of red cars
Sorting: GET /cars?sort=-manufactorer,+model -> list of cars sorted by descending manufacturers and ascending models
- 8. Version your API
Ex: /blog/api/v1
- Handle Errors with HTTP status codes
200 – OK – Eyerything is working
201 – OK – New resource has been created
204 – OK – The resource was successfully deleted
304 – Not Modified – The client can use cached data
400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid“
401 – Unauthorized – The request requires an user authentication
403 – Forbidden – The server understood the request, but is refusing it or the access is not allowed.
404 – Not found – There is no resource behind the URI.
422 – Unprocessable Entity – Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the stracktrace should be logged and not returned as response.