In OData's multipart $batch format, how do you create an order and its lines so that they succeed or fail together?

## The pieces of a multipart batch In the multipart batch format, the outer request is a `POST` to `$batch` with `Content-Type: multipart/mixed` and a `boundary` parameter. Its body is a sequence of **top-level parts**, each preceded by a boundary delimiter line, and each part is one of two things: - **An individual request**: a body part with `Content-Type: application/http` whose content is a complete HTTP request (request line, headers, blank line, body). - **A change set**: a body part that is *itself* a `multipart/mixed` document with its own boundary, holding one `application/http` part per operation. Change sets group data modification requests and action invocations; OData 4.0 states that a change set MUST NOT contain `GET` requests or other change sets. - **A Content-ID on every change-set operation**: each part representing an operation in a change set MUST carry a `Content-ID` header whose value is unique within the batch. OData 4.0 notes that it is a header of the MIME part itself, not of the HTTP request inside it. - **Three URL forms**: an inner request URL may be an absolute URI, an absolute path with a separate `Host` header, or a path relative to the batch request URL; services MUST support all three. ## Building the order-and-lines change set For a mobile client that must submit an order header and its lines as one unit: 1. Open one change set inside the batch. 2. Add the order insert, `POST Orders`, as an operation part with `Content-ID: 1`. 3. Add each line insert as its own operation part, posting to `$1/Items`. `$1` is the request identifier prefixed with `$`; the service replaces it with the URL of the entity that request created, so each line lands under the new order through its `Items` navigation property. 4. Give every operation a distinct `Content-ID` (2, 3, ...) so its response can be matched later. 5. Put credentials and the `OData-Version` header on the outer `POST`, not in the parts. ## What all-or-nothing means, and what it does not All requests in a change set are a **single change unit**: the service MUST successfully process and apply every one of them or apply none. How the service undoes an operation that had already run when a later one failed is up to the service implementation; the observable outcome is what the protocol fixes. - **Order inside a change set is not significant.** The service MAY execute its operations in any order and MAY return their responses in any order, and it MUST echo each request's `Content-ID` in the matching response. Express dependencies with `$` references, never with position. - **Order outside change sets is significant.** The service MUST process the top-level requests and change sets in the order received. - **Atomicity stops at the change set.** A `GET` before it or another change set after it is a separate unit; the batch as a whole is not one transaction. For reads that are consistent as of one point in time across the batch, OData offers the `Isolation: snapshot` header (named `OData-Isolation` in 4.0). ## The response The outer response is still `200 OK`; the change set's outcome sits in its own part. | Outcome | What the change set's part contains | |---|---| | Every operation succeeded | a nested `multipart/mixed` part with one `application/http` response per operation, each carrying its `Content-ID`, for example `201 Created` with a `Location` for each insert | | Any operation failed | a single `application/http` response, a valid OData error, that applies to the whole change set | The second row is one of the protocol's three exceptions to the rule that the response mirrors the request part for part. URLs in responses MUST NOT contain `$`-prefixed identifiers: the client gets the new order's real URL. ## Referencing rules across versions - **OData 4.0**: an entity created by an insert in a change set can be referenced by later requests in the *same* change set, in the request URL and, where the service supports it, in request bodies. - **OData 4.01**: request identifiers may be set on any request, services MAY support references across change sets (advertised with `ReferencesAcrossChangeSetsSupported` in the Capabilities `BatchSupport` annotation), and a later request may send `If-Match: $1` to reuse the ETag an earlier request returned. - **Name collisions**: if a `$`-prefixed identifier matches a top-level system resource such as `$metadata`, `$batch`, `$all`, `$entity`, `$root`, `$id` or `$crossjoin`, the system resource wins. Numeric identifiers avoid it.