|1xx Informational||Indicates transfer protocol-level information.|
|2xx Success||Indicates that the client’s request was accepted/processed successfully.|
|3xx Redirection||Informs that the client needs to take some additional action to complete their request.|
|4xx Client Error||This category of error status codes defines the client’s error.|
|5xx Server Error||These error status codes indicate the server side errors.|
|200||OK||Indicates a nonspecific success|
|201||Created||Indicates that a new resource has been created|
|202||Accepted||Indicates the start of an asynchronous action|
|204||No Content||Indicates that the body was left blank|
|301||Moved Permanently||Indicates that a new permanent URI has been assigned to the client’s requested resource.|
|303||See Other||Sent by controllers to return results that it considers optional|
|304||Not Modified||Sent to preserve bandwidth (with conditional GET)|
|307||Temporary Redirect||Indicates that a temporary URI has been assigned to client’s requested resource.|
|400||Bad Request||Indicates a non-specific client error.|
|401||Unauthorized||Indicates either client provided wrong/invalid credentials or missed to send them.|
|402||Forbidden||Indicates denied access to a protected resource.|
|404||Not Found||Sent when the client tried interacting with a URI which the REST API could not map to a resource.|
|405||Method Not Allowed||Sent when the client tried to communicate via an unsupported HTTP method.|
|406||Not Acceptable||Sent when the client tried to request data in an unsupportive type format.|
|409||Conflict||Indicates that the client attempted to violate resource state.|
|412||Precondition Failed||Informs the client that one of its pre-condition was not met.|
|415||Unsupported Media Type||Sent when the client submitted data which is of unsupported media type format.|
|500||Internal Sever Error||Tells the client that API is having problems of its own.|
|RESOURCE||GET (READ)||POST (CREATE)||PUT (UPDATE)||DELETE|
|/customers||Returns a list of customers||Create a new customer||Bulk update customers||Delete all customers|
|/customers/1234||/customers/1234||(405 – Method not allowed)||Updates a specific customer||Delete a specific customer|
Nouns are good and verbs are bad when it comes to rest standards. You can use the following easily understandable structure for every resource:
Never use GET to alter or state changes. Use GET, POST or DELETE to alter the state.
Keep the resource naming simple by following plural forms of nouns. Even though you might think that it is grammatically incorrect, but the best standard for REST practices is to use plurals.
/customers instead of /customer
/customers/12345 instead of /customer/12345
If you have some resource which is related to another resource then it is implied to use sub-resources:
GET /customers/1/products: Returns a list of products purchased by customer 1
The client-side and server-side both should know and use the format that is being used for communication. This format has to be specified in the HTTP-header.
Accept: It defines a list of acceptable response formats.
Content-Type: It defines the request format.
It is very difficult to work under situations where proper error handling is ignored. Just returning of HTTP 500 with a stacktrace log is not enough.. We need to make proper usage of the HTTP status codes that have been covered in the earlier part.
Use limit and offset for pagination. It is not only flexible for the user but also common in the leading databases.
Ascending and descending sorting should be provided. Also allow sorting over multiple fields.
We can make use of unique query parameter for all fields or may be use a query language for filtering purpose.
It is a very common practice that mobile clients wish to display only a few attributes. They don’t want to display or use all the attributes of a resource. Thus an API should have the ability that allow the mobile clients to choose the returned fields. This helps to save the mobile battery, reduce network traffic, and speeds up the API usage.
I hope the above content is easily understandable and lets you get started with developing REST API with some good level standards and consistency in your coding style. Just follow these REST best practices and you’re all set.
One last suggestion is to maintain an updated API document. This document should be shared and accessible to all concerned people. Most client-side developers should check the API document before starting the integration of web services. The doc should cover all necessary information like request URL, response body format, headers, etc. For every API try to cover with an example of request body and response bodies with all the alternative responses including error and success.