REST Response

A REST API should use an appropriate HTTP Status Code and Content Type when responding to a client's request.

Content Type

An API can support multiple response content types. It's preferred to use a JSON content type by default. When an API supports multiple content types the client can specify the desired content type with the Accept header.

The following table shows a list of common content types:

Content Type	Description
application/json	Default. Content type for a JSON response body.
application/problem+json	Content type for the Problem JSON error object for 4xx and 5xx statuse codes.
application/xml	Content type for a XML response body. Should be used when the XML is unreadable by casual users.
text/xml	Content type for a XML response body. Should be used when the XML is readable by casual users.

When more details are needed in an error response the API should use an application defined errors and supply them in an error object in the response body.

In previous version of XML RFC3023 it said that text/xml was intended for XML content which a casual user is able to read, while application/xml is preferred when the XML content is unreadable by casual users.

HTTP Status Codes

REST APIs should use the range of HTTP Status Codes to give the clients the most appropriate result of the request processing.

An API should at least use the following HTTP Status Codes for corresponding HTTP methods:

Code	Meaning	GET	POST	PUT	PATCH	DELETE
200	OK	X		X	X	X
201	Created		X
204	No Content	X		X	X	X
303	See Other		X
400	Bad Request		X	X	X
401	Unauthorized	X	X	X	X	X
403	Forbidden	X	X	X	X	X
404	Not Found	X	X	X	X	X
500	Server error	X	X	X	X	X

General

• 401 should be returned when client fails to authenticate.

• 403 should be returned when client is authenticated but does not have necessary permission to perform the operation.

• 404 should be returned when the static path of the request does not exist on the server.

• 500 should be returned when the server encounters some unexpected error, preferably along with an errors object.

GET

For retrieving a resource or a collection of resources.

• 200 should be returned on success. If a collection asked for is empty or user does not have permission to access it, 200 is still to be returned with and empty array.

• 204 should be returned when a single resource requested does not exist or the user does not have permission to access it.

When a parent resource of a sub-resource collection is not found or user does not have sufficient permissions the request should return 204 response.

POST

For creating a resource.

• 201 should be returned when the resource was created. The response body should contain the created resource.

• 303 should be returned if the resource already exists on the resource server. The response should contain the Location header with the URI of the existing resource.

• 400 should be returned if the request is invalid, i.e. the resource already exists or contains invalid fields.

PUT

For updating a existing resource.

• 200 should be returned when resource is successfully updated with the updated resource in the response.

• 204 should be returned when the resource is not found or the user does not have permission to update it.

• 400 should be returned when the request is invalid, i.e. the resource contains invalid fields.

PATCH

For making a partial update on a resource.

• 200 should be returned when resource is successfully updated with the updated resource in the response.

• 204 should be returned when the resource is not found or the user does not have permission to update it.

• 400 should be returned when the request is invalid, i.e. the resource contains invalid fields.

DELETE

For removing a resource.

• 200 should be returned when the resource is deleted and there is a need for a content in the response.

• 204 should be returned when the resource is deleted, does not exist or the user does not have permission to delete it and there is no content in response.