5.5.1 Introduction
Response codes are expected to be generalized across RESTful platforms. The specific uses detailed below are likely to be generalized. In the interest of clarity and completeness, they are included here. Please note that these response codes follow general best practices for RESTful interfaces, though they are tuned to address some of the limitations of the embedded space.
This subclause attempts to highlight HTTP response codes that are felt to be more important or that need special attention from developers. However, IEEE 2030.5 clients may encounter various HTTP response codes and, all use of, and response to HTTP response codes SHALL be standard and RFC compliant.
5.5.2 Common responses
5.5.2.1 Introduction
The following HTTP response codes are those considered to be of utmost importance for this standard.
5.5.2.2 1xx (Informational)
These response codes are informational in purpose and are used to indicate that the server is continuing to process in some fashion.
IETF RFC 7231 states, “A client MUST be able to parse one or more 1xx responses received prior to a final response, even if the client does not expect one. A user agent MAY ignore unexpected 1xx responses.”
5.5.2.3 200 ("OK")
This response code is sent to indicate a successful transaction.
This response code is often used in response to a successful GET request, with the entity-body containing a representation of the requested resource. Use of this response code in response to PUT, POST, or DELETE requests is discouraged, to avoid the potentially unnecessary traffic generated by returning the resource representation in the entity-body (see 201 [“Created”] and 204 [“No Content”]).
5.5.2.4 201 ("Created")
This response code is sent to indicate a new resource has been created, at the client’s request with a PUT or POST.
The Location header SHALL be used in conjunction with this response code to indicate the URI of the newly created resource. The inclusion of a representation of the newly created resource in the entity-body of the response is discouraged, to conserve bandwidth.
IETF RFC 7231 states, “If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response.”
5.5.2.5 204 ("No Content")
This response code is sent to indicate a successful transaction, but one where the response does not include an entity-body.
This response code is often used in response to a successful PUT or POST request, where the resource is modified, not created. This response code is also sent in response to a successful DELETE request. This response code is also sent in response to a successful GET request, where the resource exists but has an empty representation.
Further, when there are URIs that point to a resource that does not yet have content (an “empty representation”), this response code SHOULD be returned. For instance, if a client created a new resource with a POST and that new resource contains URIs pointing to resources that were not yet created and then a client were to request those linked resources, this response code would be the best response. When those resources are created (via a PUT, for instance), this response code (204) SHOULD be returned (in response to the PUT, for instance).
5.5.2.6 206 ("Partial Content")
This response code is sent to indicate the server has fulfilled the partial GET request (as specified by the Range header) for a resource. Note that IETF RFC 7233 requires the Content-Range and Date headers MUST be present in the response.
5.5.2.7 301 ("Moved Permanently")
This response code is sent to indicate that the requested resource has a new URI. The Location header SHOULD be used in conjunction with this response code to indicate the new URI of the requested resource. The entity-body of the response SHOULD be empty. Upon unexpected receipt of this response code, clients SHOULD perform resource discovery to determine which resources have changed location.
5.5.2.8 302 ("Redirect")
The Location header SHALL be used in conjunction with this response code to indicate the new URI of the requested resource. The entity-body of the response SHOULD be empty.
This response code is often used to redirect URIs requested as HTTP to HTTPS.
5.5.2.9 400 ("Bad Request")
This response code is used to indicate a client-side error and is used when no other 4xx response code is appropriate. Often, this response code indicates that the representation sent by a client with a PUT or POST is not appropriate or is malformed.
IETF RFC 7230 states, “A server MUST respond with a 400 (Bad Request) status code to any HTTP/1.1 request message that lacks a Host header field and to any request message that contains more than one Host header field or a Host header field with an invalid field-value.”
5.5.2.10 401 ("Unauthorized")
This response code is used when a client does not have proper authorization to perform the requested action on a resource.
Note, if a server did not wish a client to know of the existence of the resource, it should instead send a 404 (“Not Found”) response code.
IETF RFC 7235 states, “The server generating a 401 response MUST send a WWW-Authenticate header field (Section 4.1) containing at least one challenge applicable to the target resource.”
5.5.2.11 404 ("Not Found")
This response code is used to indicate that no resource can be found at the specified URI. This response code MAY also be used in lieu of a 401 response code.
5.5.2.12 405 ("Method Not Allowed")
This response code is used to indicate that the resource does not allow the HTTP method used by the client.
IETF RFC 7231 states, “The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource’s currently supported methods.”
5.5.2.13 406 ("Not Acceptable")
This response code is used to indicate that a server is unable to generate a response that is acceptable according to the Accept headers sent in the request.
5.5.2.14 413 ("Request Entity Too Large")
This response code is used to indicate that a server is refusing to process a request, as the request is larger than the server is willing or able to process.
5.5.2.15 416 ("Requested Range Not Satisfiable")
This response code is used to indicate that a server has received a Range request that does not overlap any of the resource content.
5.5.2.16 417 ("Expectation Failed")
This response code is used to indicate that an expectation given in an Expect request-header field cannot be met by the server or that the server does not support the given expectation.
5.5.2.17 500 ("Internal Server Error")
This response code is used to indicate that the server has an internal problem and is a generic server error response.
5.5.2.18 501 ("Not Implemented")
This response code is used when a client attempts to use a feature of HTTP (such as a method) that the server does not support.
5.5.2.19 503 ("Service Unavailable")
This response code is used when a server, due to a temporary overload condition, is unable to service a request.
5.5.3 Minimal understanding
Should a client wish to operate with minimal understanding of HTTP response codes, it need only examine the first digit of the response code to understand the general category of the response and “treat an unrecognized status code as being equivalent to the x00 status code of that class, with the exception that a recipient MUST NOT cache a response with an unrecognized status code” (IETF RFC 7231).