2.2.7.6 Batch Request
The request types defined in the preceding subsections provide mechanisms for a client to query and manipulate resources exposed by a data service whereby each request type maps to a single HTTP request/response exchange. Such request types integrate deeply with HTTP, as specified in [RFC2616], allowing a client to leverage the services (for example, caching) provided by the HTTP infrastructure deployed at large.
While the request types noted above address many common data service scenarios, as described in Protocol Examples (section 4), use cases exist where it is beneficial to enable a client of a data service to "batch" up a group of requests and send that Batch to the data service in a single HTTP request. This section defines a Batch request type that reduces the number of roundtrips to a data service for applications that need to make numerous requests and a change set syntax as a way to logically group a set of requests in a single unit within a batch.
A data service MAY<67> support requests of this type. If a data service does not implement support for a Batch request, it has to return a 4xx response code in the response to any Batch request sent to it.
Batch request MUST use the HTTP POST method and the URI specified by the client in the HTTP request line MUST be a valid data service URI that identifies the batch endpoint of a data service, see URI9 in Resource Path: Semantics (section 2.2.3.5).
Query operations and change sets MAY<68> be intermixed within a Batch request and occur in any order. A query operation MUST consist of a single Retrieve request, as defined in Retrieve Request Types (section 2.2.7.2), or of an Invoke Request (section 2.2.7.5) that uses the HTTP GET method. Change sets MUST consist of one or more of the following request types:
Invoke Request (section 2.2.7.5)), by using the HTTP PUT, POST, PATCH, MERGE, or DELETE methods.
Request types within a batch MUST be performed by the server with the same semantics used when the request type is used outside of the context of a batch.
The order of change sets and query operations within a Batch request is significant, as it states the order in which the data service MUST process the components of a Batch. The order of requests within a change set MUST NOT be significant such that a data service can process the requests in a change set in any order. All operations in a change set represent a single change unit so the server MUST successfully process and apply all the requests in the change set or else apply none of the requests in the change set. It is up to the data service to define rollback semantics to undo any requests within a change set that have been applied before another request in that same change set failed and thereby honor this all-or-nothing requirement.
A Batch request is represented by using a single HTTP POST request with a payload of the multipart/mixed media type, as specified in [RFC2046]. The request MUST use Multipurpose Internet Mail Extensions (MIME) version 1.0 and include a Content-Type header that conforms to the contentTypeMime rule in the grammar shown in the following Batch request headers listing. Each change set and/or query operation in a Batch request is represented as a distinct MIME part, separated by the boundary defined in the Content-Type header of the request. Implementers SHOULD follow the recommendations for boundary generation described in [RFC2046] section 5.1.
Preambles and Epilogues in the MIME payload, as defined in [RFC2046], are valid but MUST be ignored by the server.
Note Unlike the other grammars described in Request Types (section 2.2.7), all ABNF grammars defined in this document that add constraints to rules defined in MIME-related RFCs, [RFC2045], and [RFC2046], do not follow the ABNF rules defined in [RFC2616] section 2.1.
-
contentTypeMime = "Content-Type:multipart/mixed;" ; see [RFC2045] section 5 & [RFC2046] section 5.1 *SP "boundary=" boundary ; see [RFC2046] section 5.1.1
Listing: Batch Request Headers