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:
Default. Content type for a JSON response body.
Content type for the Problem JSON error object for 4xx and 5xx statuse codes.
Content type for a XML response body. Should be used when the XML is unreadable by casual users.
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:
200
OK
X
X
X
X
201
Created
X
202
Accepted
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
401should be returned when client fails to authenticate.403should be returned when client is authenticated but does not have necessary permission to perform the operation.404should be returned when the static path of the request does not exist on the server.500should be returned when the server encounters some unexpected error, preferably along with an errors object.
GET
GETFor retrieving a resource or a collection of resources.
200should be returned on success. If a collection asked for is empty or user does not have permission to access it,200is still to be returned with and empty array.204should 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
POSTFor creating a resource.
201should be returned when the resource was created. The response body should contain the created resource.202should be returned when the request has been accepted for processing but may not have been acted upon or completed yet.303should be returned if the resource already exists on the resource server. The response should contain theLocationheader with the URI of the existing resource.400should be returned if the request is invalid, i.e. the resource already exists or contains invalid fields.
PUT
PUTFor updating a existing resource.
200should be returned when resource is successfully updated with the updated resource in the response.204should be returned when the resource is not found or the user does not have permission to update it.400should be returned when the request is invalid, i.e. the resource contains invalid fields.
PATCH
PATCHFor making a partial update on a resource.
200should be returned when resource is successfully updated with the updated resource in the response.204should be returned when the resource is not found or the user does not have permission to update it.400should be returned when the request is invalid, i.e. the resource contains invalid fields.
DELETE
DELETEFor removing a resource.
200should be returned when the resource is deleted and there is a need for a content in the response.204should 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.
Last updated