REST runs the error handler using the HTTP 1.1 status codes. For instance:
• 200 -> OK: This is often used with the GET verb
• 201 -> Created: This is often used by the put/post verbs
• 204 -> No Content: This is often for the DELETE verb
• 400 -> Invalid Request: This often means an invalid request for the POST/PUT verbs
• 404 -> Not Found: This is often used with the GET verb
• 500 -> Internal Server Error - Unexpected Server Error: This is often used by all the verbs
REST API patterns
There are some commons patterns for good and clear REST API designs, as follows:
• Use nouns; do not use verbs: Often, you can use standard URIs, such as /cars/ or /members/. You should not use /getCars/ or getMembers/ because you are using the URI with a verb, and the verb already tells the actions.
• GET method should not change state: If you want to change the state of the server, you will need to use verbs such as put, post, or delete. get should not change the state of the server, so it should always be safe calling GET as many times as you want. This is called idempotent.
• Prefer sub-resource relation: Let's say we have a resource called /users/, and a user has projects. It's always a good idea to use sub-resources, such as /users/1/projects/2, because we have a relationship between users and projects.
• Use HTTP headers: HTTP headers should be used for serialization, security, and all the kinds of metadata your application needs. The HTTP Headers are often used for content negotiation. For instance, you might do the following:
HTTP HEADER Content-Type = XML - GET /cars/1 HTTP HEADER Content-Type = JSON - GET /cars/1
• The URI is the same; however, based on the header type, it will return data in XML or JSON format.
• Filter, Sorting and Pagination: Sometimes, your data may be big. It's always a good idea to provide mechanisms to sort, filter, and paginate as follows:
GET /projects/1/tasks?by=priority -> Sorting
GET /projects/1/tasks?status=done -> Filter
GET /projects/1/tasks?limit=30&offset=5 -> Pagination
There are two ways to perform API versioning. First strategy is to version by the endpoint explicit such as /v1/cars. The second strategy is based on metadata such as /cars/, but then you will pass an HTTP HEADER version as v1.
Both strategies have pros and cons. Explicit versioning is more clear, and you can always create a new version and don't break your consumers. Header strategy is more elegant; however, it can get tricky to manage.
Some anti-patterns to be avoided
There are several traps in the REST API design, but the following things need to be avoided:
• GET verb for everything
• Ignoring HTTP headers such as MIME-types
• Returning 200 when an error happens
• Returning 500 for an invalid parameter or a missing parameter