HTTP Binding

This guide provides information about Resource Binding.

Support for RESTful web services is based on JSR 311: JAX-RS: The Java API for RESTful Web Services, which implies binding to the Hypertext Transfer Protocol, version 1.1, RFC 2616 . Other protocol binding are out of scope for the near future thus the RESTful API specifications may not be entirely generic but bound to the HTTP methods instead of the generic REST operations.

CRUD Mapping

CRUD method	HTTP method	Description
CREATE	POST	Creates a new resource. The identifiers of the new resource and the entity that it represents are generally unknown to the client, thus generated and assigned by the server upon resource creation. HTTP POST method shall be used against the new resource parent's URI which is generally a collection resource - the representation of the new resource shall be included in the HTTP request message body. It is recommended that RESTful web services employ usage of HTTP POST method only for resource creation. On successful execution of the creation procedure, the HTTP response shall contain a Location header holding the URI of the newly created resource which full representation shall be included in the response message body. Resource representations transferred with HTTP POST method shall include all of the mandatory and any of the optional resource fields annotated with [CREATE].
RETRIEVE	GET	Retrieves the representation of a certain resource which can be an instance or a collection resource. On successful execution of this procedure, the resource representation shall be included in the HTTP response message body. Resource representations transferred with HTTP GET method shall include all of the mandatory and any of the optional resource fields annotated with [RETRIEVE].
UPDATE	PUT	Updates a certain instance resource based on a transferred resource representation. HTTP PUT method shall be used against the resource's URI – RFC 7386 JSON Merge Patch compliant representation shall be included in the HTTP request message body, describing a set of modifications to the target resource's representation. The transferred representation should contain fields which are controlled and modifiable by the client, thus entity identifiers and resource links are not expected and should be ignored by the server.
DELETE	DELETE	Removes a certain resource which can be an instance or a collection resource. On successful execution of this procedure the deleted resource's representation shall no longer be accessible.

Depending on the CRUD operation various representations of a given resource may be transferred including different resource fields. It is recommended that the resource descriptions contained in the resource model of RESTful web services clarify the resolution of the various resource fields with respect to the CRUD operation:

resource fields annotated with [GET] may be included in resource representations transferred with RETRIEVE (HTTP GET) requests, depending on the field resolution.
resource fields annotated with [POST] may be included in resource representations transferred with CREATE (HTTP POST) requests, depending on the field resolution.
resource fields annotated with [PUT] may be included in resource representations transferred with UPDATE(HTTP PUT) requests, depending on the field resolution.

Resource fields that are not expected in a resource representation transferred with a particular CRUD operation should be ignored by the server. Resource fields which values are generated and controller by the server such as resource and entity identifiers and hypermedia links are not expected in POST or PUT requests, thus should be ignored by the server. Plain hypermedia links themselves shall never be included in representations included in PUT and POST requests. However, fields that represent expandable hypermedia links may be annotated with [POST] and [PUT] in which case the links are assumed expanded and the annotations in the linked resources shall be considered.

Bulk Operations

Supporting bulk resource updates via updates of collection resources is ambiguous and do not conform to the common practices, therefore not recommended. Bulk operations may be supported via dedicated batch API. Batching allows passing instructions for several operations in a single HTTP request, defining of dependencies between related operations may be supported. The server may process each of the independent operations in parallel and will process your dependent operations sequentially. Once all operations have been completed, a consolidated response will be passed back to the client and the HTTP connection will be closed.

Additionally, the update or creation of a single instance resource may require multiple invocations of the underlying API which are neither atomic, nor transactional. However, updates of multiple fields of a single instance resource should not be considered a bulk operation. It is recommended that implementation of the RESTful web service tries to invoke all setters and return an accumulated error to the client in case some of the operations fail.

Common Request Headers

Header	Description	Required
Accept	Identifies which media type(s) this client is prepared to accept from the server.	Recommended, on requests that will produce a response message body. If this header is absent then application/json is assumed.
Authorization	Identifies the authorized user making this request.	Yes, on all requests.
Content-Length	Contains the length of the message, in decimal value of bytes. If the message has no content then the message must contain "Content-Length: 0".	Yes, on all requests.
Content-Type	Describes media type specifying the representation and syntax of the request message body.	Yes, on requests that contain a message body.
X-Gateway-Identifier	Defines the unique identifier of the gateway in case the client is operating remotely with the Remote Management M2M RESTful web services and is scoped to a single gateway.	Only if working in scoped case and if the gateway identifier is not explicitly stated in the request URI.
X-Representation-Expand	This header defines a list of resource links that will be expanded in the representation. For more details, please see Customizing Resource Representations.	Only if customizing the resource representation transferred by expanding hypermedia links is desired.
X-Representation-Exclude	This header defines a list of resource fields that will be excluded from the resource representation. For more details, please see Customizing Resource Representations.	Only if customizing the resource representation transferred by excluding fields is desired.
X-Representation-Include	The header defines a list of resource fields that will be selectively included in the resource representation. For more details, please see Customizing Resource Representations.	Only if customizing the resource representation transferred by selectively including fields is desired.
X-Operation-Arguments	This header defines additional operation arguments that can be used to customize various REST operations like creating or deleting resources. The support of operation arguments depends on the underlying services. If no operation arguments are specified then the default are applied. Operation arguments can also be defined using arguments query parameter.	Only if a REST operation customization is desired.
Range	Clients that wish to use paginated retrieval of collection resources shall include this header in HTTP requests. For more details refer to Limiting Query Results and Pagination.	Only if pagination for a particular collection resources is to be used.

Common Response Headers

Header		Required

X-Representation-Include	The header defines a list of resource fields that are selectively included in the resource representation. For more details, please see Customizing Resource Representations.	Only if the response contains a resource representation which has been customized via field inclusion constraints.
X-Representation-Expand	This header defines a list of resource links that are expanded in the resource representation contained in the response. For more details, please see Customizing Resource Representations.	Only if the response contains a resource representation which has been customized via hyper media link expansion constraints.
X-Representation-Exclude	This header defines a list of resource fields that are excluded from the resource representation. For more details, please see Customizing Resource Representations.	Only if the response contains a resource representation which has been customized via field exclusion constraints.
Location	Returns a resource absolute URI that can be used to request a representation of the newly created resource or redirect to another resource, e.g in case of asynchronous operation executions.	Yes, on responses to requests that create new server side resources or redirect another resources accessible via a URI.
Content-Type	Describes media type specifying the representation and syntax of the response message body.	Yes, on responses that contain a message body.
Content-Range	Clients that have requested paginated retrieval of collection resources shall receive this header included in HTTP response. For more details refer to: Limiting Query Results and Pagination.	Only if pagination of a collection resource using the Range HTTP header is required.
Content-Location	Returns a resource URI that can be used to request a representation of the newly created resource or redirect to another resource, e.g in case of asynchronous operation executions.	Yes, on responses to requests that create new server side resources or redirect another resources accessible via a URI.
Content-Length	Contains the length of the message, in decimal value of bytes.	Yes, on responses that contain a message body.

HTTP Status Codes

HTTP Status	Description
200 OK	The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a Location header containing the canonical URI for the newly created resource.
201 Created	A request that created a new resource was completed, and no response body containing a representation of the new resource is being returned. A Location header containing the canonical URI for the newly created resource should also be returned.
202 Accepted	The request has been accepted for processing, but the processing has not been completed. Per the HTTP/1.1 specification, the returned entity (if any) should include an indication of the request's current status, and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.
204 No Content	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. The response MAY include new or updated meta information in the form of entity-headers, which if present should be associated with the requested variant. The 204 response must not include a message-body, and thus is always terminated by the first empty line after the header fields.
303 See Other	The response to the request can be found under a different URI and should be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource. The 303 response must not be cached, but the response to the second (redirected) request might be cacheable. The different URI should be given by the Location field in the response. Unless the request method was HEAD, the entity of the response should contain a short hypertext note with a hyperlink to the new URI(s).
400 Bad Request	The request could not be processed due to malformed syntax (such as invalidation input field, a missing required value, invalid or unexpected query parameters, etc.).
401 Unauthorized	The authentication credentials included with this request are missing or invalid. Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. See Basic access authentication and Digest access authentication.
403 Forbidden	The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it should describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.
404 Not Found	The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code should be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
405 Method Not Allowed	The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response must include an Allow header containing a list of valid methods for the requested resource. Used to indicate that the requested URL exists, but the requested HTTP method is not applicable.
406 Not Acceptable	The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. Unless it was a HEAD request, the response should include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field.
409 Conflict	A creation or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier already assigned to some existing resource).
410 Gone	Indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource again in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a "404 Not Found" may be used instead.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 Internal Server Error response.