Best practices for REST API design

One of the key advantages of REST APIs is that they provide a great deal of flexibility. Data is not tied to resources or methods, so REST can handle multiple types of calls, return different data formats and even change structurally with the correct implementation of hypermedia. This flexibility allows developers to?build an API?that meets your needs while also meeting the needs of very diverse customers.?

REST API is extensively considered as the standard protocol for the web APIs. One of the reasons for the popularity of REST API is that?it is user-friendly and it is easy to understand for the developers to code on it.?

Error Handling and Response Codes

Most of the time, requesting data from an API will return the data we asked for in the way we specified. But often, errors happen and the back-end cannot process the request for any reason. It is important, that the API handles these exceptions and returns an appropriate error message so that clients know what to do, eg. whether to ask again, or fix the request, or wait for some time.

There is a whole list of status code your API can return with the response, you can check it?here. They are basically grouped into the following families:

• 1xx: informational
• 2xx: success
• 3xx: redirection
• 4xx: client error
• 5xx: server error

The ones you will come across more often and that will be more helpful are:

• 200 OK: the server got the request and responded accordingly.
• 201 Created: a new resource has been created; you should return this code when handling a POST action on a collection, for instance.
• 202 Accepted: the request has been accepted but not processed; it is queued for execution and might not be fulfilled. You can use this code when a request generates an action that will happen asynchronously, like a data update or an email.
• 204 No Content: the request was processed but the server does not have any content to return. You can use this code when handling DELETE requests.
• 301 Moved Permanently: the URL changed permanently and it can be found elsewhere.
• 302 Found & 303 See Other: the URL changed temporarily and can be found elsewhere.
• 304 Not Modified: use this code to implement caching systems. If the request headers?If-Modified-Since?or?If-None-Match?are used and the server does not have a newer version to provide, then return?304?so that the client can use the copy it has stored locally.
• 400 Bad Request: the request is malformed. Use this code to tell the client to re-send the information correcting the format issue.
• 401 Unauthorized: the user is unauthenticated and cannot be granted access to a restricted resource. Logging into the system will solve this error.
• 403 Forbidden: the user is authenticated but her cannot access this resource. Logging into the system will not change this error.
• 404 Not Found: as it sounds, probably the most well-known error code on the Internet.
• 405 Method Not Allowed: use this code when the client requests an HTTP verb that the given resource cannot handle, like POST on individual resources or PUT on collections.
• 415 Unsupported Media Type: use this code when the content type used or requested by the client is not supported by your API, like JSON when you would expect XML.
• 500 Internal Server Error: an unexpected error prevented the server from returning a response.
• 503 Service Unavailable: the server is temporarily unavailable because it’s overloaded or due to maintenance reasons.

We should make sure that the right HTTP codes are returned along with the response, whether that was successful or produced an error. This will help your API consumers understand what your system is saying and build their applications on top of it. It will also ease debugging and testing your back-end as well — you might find edge cases faster by looking at the error codes returned.