OData Batch Processing Version 1.

0
Working Draft 01
22 August 2012
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Barbara Hartel (barbara.hartel@sap.com), SAP AG
Ram Jeyaraman (Ram.Jeyaraman@microsoft.com), Microsoft
Editor:
Mike Pizzo (mikep@microsoft.com), Microsoft
Additional artifacts:
This prose specification is one component of a Work Product which also includes:
 OData Protocol
 OData URL Conventions
 OData Common Schema Definition Language
 OData ABNF Construction Rules
 OData JSON Format
 OData ATOM Format
Related work:
 None
Declared XML namespaces:
 None
Abstract:
The Open Data Protocol (OData) enables the creation of REST-based data services, which allow
resources, identified using Uniform Resource Identifiers (URLs) and defined in a data model, to
be published and edited by Web clients using simple HTTP messages. This document defines a
format for submitting batch requests, and retrieving batch responses, from an OData Service.
Status:
This Working Draft (WD) has been produced by one or more TC Members; it has not yet been
voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a
Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to
approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and reapprove it any number of times as a Committee Draft.

Copyright © OASIS Open 2012. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual
Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that
comment on or otherwise explain it or assist in its implementation may be prepared, copied, published,
and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
and this section are included on all such copies and derivative works. However, this document itself may
not be modified in any way, including by removing the copyright notice or references to OASIS, except as
needed for the purpose of developing any document or deliverable produced by an OASIS Technical
Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be
followed) or as required to translate it into languages other than English.

odata-batch-processing-v1.0-wd01
Standards Track Draft

Working Draft 01
Copyright © OASIS Open 2012. All Rights Reserved.

02 August 2012
Page 1 of 15

INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. All Rights Reserved.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. odata-batch-processing-v1. This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES.The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns. 02 August 2012 Page 2 of 15 . EXPRESS OR IMPLIED.

................................................. 14 B....................................... 02 August 2012 Page 3 of 15 ......................................... Revision History........................................................................................................................Table of Contents 1 Introduction................................................... Acknowledgments.....................................................1 Sub-subsidiary section................................................................... 13 Appendix B...... 12 Appendix A..........................................................................................................................8 4 Responding to a Batch Request...........................................3 Non-Normative References... 4 2 Introduction......... 6 3.................. 4 1....................................... 15 odata-batch-processing-v1................2 Normative References..........................................1...................................................................................................................................................................................................................................... 5 3 Sending a Batch Request................................. 14 Appendix C.................................1 Terminology.................................. 4 1.............................. 6 3..0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012..................................................................1 Subsidiary section..................................................................................................... 6 3....................... 14 B................1 Batch Request Headers.. 4 1..............................................................................................................................................................................................................1 Referencing Requests in a Change Set........................................................................................... All Rights Reserved.................................................................................................... Non-Normative Text...............................2.................................................................... 10 5 # Conformance..............2 Batch Request Body......................................................................................

DD Month 2012.0/csd01/odata-v1. S.oasis-open.ietf.0. http://docs. 1996.org/odata/odata-urlconventions/v1. November. OData ATOM Format Version 1.”. OData JSON Format Version 1. OData Common Schema Definition Language (CSDL) Version 1. DD Month 2012.txt 1. “SHOULD NOT”.oasis-open.org/odata/odata-jsonformat/v1. http://docs.0. OASIS Committee Specification Draft 01.0.1. and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].0-csd01. http://docs. http://www. RFC 2119. OASIS Committee Specification Draft 01.doc. et al.txt. http://docs. “Hypertext Transfer Protocol -. R. “Key words for use in RFCs to Indicate Requirement Levels”.doc. “RECOMMENDED”.1 Terminology The key words “MUST”..0/csd01/odata-url-conventions-v1.3 Non-Normative References None odata-batch-processing-v1.0-csd01. http://www. “REQUIRED”. RFC 2616. et al.0csd01. “SHOULD”. OASIS Committee Specification Draft 01. All Rights Reserved.org/odata/odata-csdl/v1.0/csd01/odata-atom-format-v1.oasis-open.. RFC 2046. “MAY”.. http://www.org/rfc/rfc2046.ietf. “MUST NOT”. DD Month 2012. OData ABNF Construction Rules Version 1.org/odata/odata-atomformat/v1.0.oasisopen. OASIS Committee Specification Draft 01. "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types". Bradner.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. OData URL Conventions Version 1. OASIS Committee Specification Draft 01. March 1997.txt. 02 August 2012 Page 4 of 15 .0/csd01/odata-abnf-construction-rules-v1.0.doc. BCP 14. Freed. “SHALL”.doc.0-csd01. DD Month 2012.HTTP/1.0. Fielding.0/csd01/odata-json-format-v1.0/csd01/odata-csdl-v1.1 Introduction [All text is normative unless otherwise labeled] 1.doc.oasis-open.0-csd01. DD Month 2012. http://docs. N.ietf.0-csd01. http://docs.org/rfc/rfc2616. 1.org/odata/odata-abnfconstruction-rules/v1.doc. OASIS Committee Specification Draft 01.2 Normative References [OData-Core] [OData-URL] [OData-ABNF] [OData-CSDL] [OData-ATOM] [OData-JSON] [RFC2119] [RFC2616] [RFC2046] OData Protocol Version 1. “SHALL NOT”. DD Month 2012. June 1999.org/rfc/rfc2119.org/odata/odata/v1.oasis-open.

Unless otherwise specified. This document covers both how Batch operations are represented and processed. odata-batch-processing-v1. the contents of this document is defined as part of OData version 1. This document builds on the 'Interaction Semantics' section of [OData-Core] and describes how an OData implementation MAY support executing multiple operations sent in a single HTTP request through the use of Batching. 02 August 2012 Page 5 of 15 .2 Introduction The OData protocol defines a way to query and manipulate data (described using an EDM model) using a simple set of operations.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. All Rights Reserved.

1 Host: odata. into a single HTTP request payload. The batch request MUST contain a Content-Type header specifying a content type of "multipart/mixed" and a boundary specification as defined in [RFC2046] is defined in the Batch Request Body section below. are valid but are assigned no meaning and thus MUST be ignored by processors of batch requests.1 Batch Request Headers Batch requests MUST be submitted as a single HTTP POST request to the batch endpoint of a service. each of which may have a different content type (as described in [OData-Atom] and [OData-JSON]). 3.0 MaxDataServiceVersion: 3. as described in [OData-Core]. Service Root URIs are defined in [OData-Core].e. Each MIME part body which represents a single request SHOULD NOT:  Include authentication or authorization related HTTP headers because it is unlikely the infrastructure used for authentication will parse and utilize such headers. A query operation in the context of a batch request is either a query or Function invocation request as described in [OData-Core]. A MIME part representing a query operation MUST include a Content-Type header with value application/http and a ContentTransfer-Encoding header with value binary. POST /service/$batch HTTP/1. The contents of a MIME part representing a ChangeSet MUST itself be a multipart MIME document (see [RFC2046]) with one part for each operation that makes up the ChangeSet. each query operation and ChangeSet MUST be represented as a distinct MIME part (i. as described in the Versioning section of [OData-Core]. as defined in [RFC2046]. ChangeSets MUST NOT contain query operations and MUST NOT be nested (i.e. All Rights Reserved.0 content-type: multipart/mixed. boundary=batch(36522ad7-fc75-4b56-8c7156071383e77b) <Batch Request Body> As shown in the example above and. Each part represnting an operation in the ChangeSet MUST include the same headers (Content-Type and Content-Transfer-Encoding) and associated values as previously described for query operations. 3.0 message [RFC2046]. odata-batch-processing-v1. In a batch request body. within a single request. A batch request MUST be represented as a Multipart MIME v1. which MUST be located at the URI http:///$batch. Finally. batch requests SHOULD contain applicable DataServiceVersion headers. 02 August 2012 Page 6 of 15 .3 Sending a Batch Request Batch requests allow grouping multiple operations. Action invocations or Service Operation invocations described in [OData-Core]. a ChangeSet cannot contain a ChangeSet). Preambles and Epilogues in the MIME payload.2 Batch Request Body The body of a batch request MUST be made up of an ordered series of query operations and/or ChangeSets.e.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012.org DataServiceVersion: 1. batch requests MUST NOT include an X-HTTP-Method header (i. is separated by the boundary defined in the Content-Type header). a standard format allowing the representation of multiple parts. use POST tunelling) as batch requests are by definition POST only. A ChangeSet is an atomic unit of work consisting of an unordered group of one or more of the insert/update/delete operations.

The example below shows a sample batch request that contains the following operations in the order listed: 1.1 Host: host Content-Type: multipart/mixed.type=entry Content-Length: ### <AtomPub representation of a new Customer> --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) Content-Type: application/http Content-Transfer-Encoding:binary PUT /service/Customers('ALFKI') HTTP/1.1 Host: host Content-Type: application/atom+xml.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. Range. or TE headers because their contents will be ignored. All Rights Reserved. For example. From. Max-Forwards. Update request 3. a processor MAY choose to disallow chunked encoding to be used by such HTTP requests. query request 2. boundary=changeset_77162fcd-b8da-41ac-a9f89357efbbd621 Content-Length: ### --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) Content-Type: application/http Content-Transfer-Encoding: binary POST /service/Customers HTTP/1. Insert entity 2. Processors of batch requests MAY choose to disallow additional HTTP constructs in HTTP requests serialized within MIME part bodies.1 Host: host Content-Type: application/json If-Match: xxxxx Content-Length: ### <JSON representation of Customer ALFKI> odata-batch-processing-v1. 02 August 2012 Page 7 of 15 . Change Set that contains the following requests: 1. boundary=batch_36522ad7-fc75-4b56-8c7156071383e77b --batch_36522ad7-fc75-4b56-8c71-56071383e77b Content-Type: application/http Content-Transfer-Encoding:binary GET /service/Customers('ALFKI') Host: host --batch_36522ad7-fc75-4b56-8c71-56071383e77b Content-Type: multipart/mixed. second query request POST /service/$batch HTTP/1. Include Expect.

1 Host: host Content-Type: multipart/mixed. The example below shows a sample batch request that contains the following operations in the order listed: A ChangeSet that contains the following requests: 1. boundary=batch_36522ad7-fc75-4b56-8c7156071383e77b --batch_36522ad7-fc75-4b56-8c71-56071383e77b Content-Type: multipart/mixed. $ acts as an alias for the URI that identifies the new entity.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012.1 Host: host Content-Type: application/atom+xml.type=entry odata-batch-processing-v1. When used in this way. request bodies are excluded in favor of English descriptions inside <> brackets and DataServiceVersion headers are omitted. Insert a new entity (with Content-ID = 1) 2. 02 August 2012 Page 8 of 15 . in the example. boundary=changeset_77162fcd-b8da-41ac-a9f89357efbbd621 Content-Length: ### --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 1 POST /service/Customers HTTP/1. then the new entity represented by that part may be referenced by subsequent requests within the same ChangeSet by referring to the Content-ID value prefixed with a $ character.2.1 Host: host --batch(36522ad7-fc75-4b56-8c71-56071383e77b)-Note: For brevity. 3.type=entry Content-Length: ### <AtomPub representation of a new Customer> --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) Content-Type: application/http Content-Transfer-Encoding: binary POST $1/Orders HTTP/1.1 Referencing Requests in a Change Set If a MIME part representing an Insert request within a ChangeSet includes a Content-ID header.1 Host: host Content-Type: application/atom+xml. Insert a second new entity (references request with Content-ID = 1) POST /service/$batch HTTP/1. All Rights Reserved.--changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)---batch(36522ad7-fc75-4b56-8c71-56071383e77b) Content-Type: application/http Content-Transfer-Encoding:binary GET service/Products HTTP/1.

All Rights Reserved.Content-Length: ### <AtomPub representation of a new Order> --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)---batch(36522ad7-fc75-4b56-8c71-56071383e77b)-- odata-batch-processing-v1. 02 August 2012 Page 9 of 15 .0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012.

1 200 Ok Content-Type: application/atom+xml.2. The order of ChangeSets and query operations in a Batch request is significant as a service MUST process the components of the Batch in the order received.0 Content-Length: #### Content-Type: multipart/mixed. Finally.1 202 Accepted DataServiceVersion: 1. a batch response body MUST match one-to-one with the corresponding batch request body. boundary=changeset(77162fcd-b8da-41ac-a9f8odata-batch-processing-v1. Instead. using the application/http media type and a Content-Transfer-Encoding header with a value of binary.type=entry Content-Length: ### <AtomPub representation of the Customer entity with EntityKey ALFKI> --batch(36522ad7-fc75-4b56-8c71-56071383e77b) Content-Type: multipart/mixed. etc) the service MUST return a 202 Accepted HTTP response code to indicate that the request was accepted for processing. All operations in a ChangeSet represent a single change unit so a service MUST successfully process and apply all the requests in the ChangeSet or else apply none of them. It is up to the service implementation to define rollback semantics to undo any requests within a ChangeSet that may have been applied before another request in that same ChangeSet failed and thereby honor this all-or-nothing requirement. a response to a query operation in a batch MUST be formatted exactly as it would have appeared outside of a batch as described in Querying Data section of [OData-Core].0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012.4 Responding to a Batch Request Requests within a batch MUST be evaluated according to the same semantics used when the request appears outside the context of a batch. referencing the batch request in section 2. The order of requests within a ChangeSet is not significant as a service MAY process the requests within a ChangeSet in any order. The requests within the body of the batch may subsequently fail or be malformed. a single response. assume all the requests except the final query request succeed. In this case the response would be as shown in the following example. boundary=batch(36522ad7-fc75-4b56-8c7156071383e77b) --batch(36522ad7-fc75-4b56-8c71-56071383e77b) Content-Type: application/http Content-Transfer-Encoding: binary HTTP/1. HTTP/1. this enables batch implementations to stream the results. For example. such that the same multipart MIME message structure defined for requests is used for responses. If the set of request headers of a Batch request are valid (the Content-Type is set to multipart/mixed. however. If the service receives a Batch request with an invalid set of headers it MUST return a 4xx response code and perform no further processing of the request. All Rights Reserved. is returned that applies to all requests in the Change Set and MUST be formatted according to the Error Handling section of [OData-Core]. 02 August 2012 Page 10 of 15 . A response to a batch request MUST contain a Content-Type header with value multipart/mixed. Structurally. The exception to this rule is that when a request within a Change Set fails. but the processing yet to be completed. the Change Set response is not represented using the multipart/mixed media type.

1 204 No Content Host: host --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621)---batch(36522ad7-fc75-4b56-8c71-56071383e77b) Content-Type: application/http Content-Transfer-Encoding: binary HTTP/1.9357efbbd621) Content-Length: ### --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) Content-Type: application/http Content-Transfer-Encoding: binary HTTP/1.1 201 Created Content-Type: application/atom+xml.type=entry Location: http://host/service.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. 02 August 2012 Page 11 of 15 . All Rights Reserved.1 404 Not Found Content-Type: application/xml Content-Length: ### <Error message> --batch(36522ad7-fc75-4b56-8c71-56071383e77b)-- odata-batch-processing-v1.svc/Customer('POIUY') Content-Length: ### <AtomPub representation of a new Customer entity> --changeset(77162fcd-b8da-41ac-a9f8-9357efbbd621) Content-Type: application/http Content-Transfer-Encoding: binary HTTP/1.

5 # Conformance The last numbered section in the specification must be the Conformance section.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. Conformance Statements/Clauses go here. All Rights Reserved. 02 August 2012 Page 12 of 15 . [Remove # marker] odata-batch-processing-v1.

0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012. 02 August 2012 Page 13 of 15 . Affiliation | Individual Member] [Participant Name. Acknowledgments The following individuals have participated in the creation of this specification and are gratefully acknowledged: Participants: [Participant Name. Affiliation | Individual Member] odata-batch-processing-v1.Appendix A. All Rights Reserved.

Non-Normative Text text B.1 Subsidiary section text B. All Rights Reserved. 02 August 2012 Page 14 of 15 .Appendix B.1 Sub-subsidiary section text odata-batch-processing-v1.0-wd01 Standards Track Draft Working Draft 01 Copyright © OASIS Open 2012.1.

All Rights Reserved.Appendix C. Revision History Revision 1.0-wd01 Standards Track Draft Editor Michael Pizzo Changes Made Translated Contribution to OASIS format/template Working Draft 01 Copyright © OASIS Open 2012.0 Date 2012-08-22 odata-batch-processing-v1. 02 August 2012 Page 15 of 15 .