13.3 Synchronous Batch Request
SData uses Atom feeds for batch requests. It makes use of the CRUD mechanisms that have been described previously and that apply to individual Atom entries. An SData batch is nothing more than a feed of unpackaged raw XML data containing entries, with a simple markup (http:httpMethod) to tag each entry with the operation that it requests. Here is an example of an SData batch request:
POST /sdata/myApp/myContract/-/salesOrders/$batch HTTP/1.1 Content-Type: application/atom+xml; type=feed
<feed xmlns:sdata="http://schemas.sage.com/sdata/2008/1"
xmlns:http="http://schemas.sage.com/sdata/http/2008/1"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:sle="http://www.microsoft.com/schemas/rss/core/2005"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.w3.org/2005/Atom">
<title>Sales Orders</title>
<id>http://www.example.com/sdata/myApp/myContract/-/salesOrders/$batch</id>
<updated>2008-03-31T13:46:45Z</updated>
<entry>
<id/>
<title/>
<content/>
** <http:httpMethod>POST</http:httpMethod>**
<sdata:payload>
<salesOrder xmlns="http://schemas.sage.com/myContract"
sdata:uuid="BE7D7445-7FA4-4c67-AC22-5F6446314771" >
<orderDate>2008-03-31</orderDate>
<contact sdata:key="216" />
<subTotal>202.70</subTotal>
<orderLines>
<salesOrderLine
sdata:uuid="5FB95DE2-8548-48ac-8868-8006238EEBF0">
<product sdata:key="72"/>
<orderQty>1</orderQty>
<unitPrice>81.70</unitPrice>
</salesOrderLine>
<salesOrderLine
sdata:uuid="A2744351-1891-4365-948D-80A32594A14E">
<product sdata:key="43" />
<orderQty>2</orderQty>
<unitPrice>60.50</unitPrice>
</salesOrderLine>
</orderLines>
</salesOrder>
</sdata:payload>
</entry>
<entry>
<id>http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')</id>
<title>Sales Order 43661</title>
<updated>2008-03-31T13:46:45Z</updated>
<content>Sales order 43661: amount 39422,1198</content>
** <http:httpMethod>PUT</http:httpMethod>**
** <http:ifMatch>3nqPeQqoGoxQB5xf3NIijw==</http:ifMatch>**
<sdata:payload>
<salesOrder xmlns="http://schemas.sage.com/myContract">
<shipDate>2008-03-31</shipDate>
</salesOrder>
</sdata:payload>
</entry>
<!-- ... more entries ... -->
</feed>
In this batch, the first entry creates a new sales order resource, while the second entry updates the shipping date of an existing sales order resource.
The action that needs to be carried out on each entry is indicated by the http:httpMethod element.
If the action needs additional information transmitted via an HTTP header in the non batch case, then the information is placed in an http:xxx element where xxx is the HTTP header name in camel case. For now only http:ifMatch is used in batch requests but more “header elements” may be introduced in the future.
<http:httpMethod>PUT</http:httpMethod> <http:ifMatch>3nqPeQqoGoxQB5xf3NIijw==</http:ifMatch>
If we ignore these elements, the entry is identical to the entry that would be submitted individually with an HTTP PUT request. Find out more.
The four HTTP methods are supported in the http:httpMethod element: POST, PUT, DELETE and GET.
The GET method is rarely used because the usual way to read several resources in one request is to do a query. But this feature can be used if the consumer has a precise list of resource ids that it needs to read. In some cases it may be easier to build a batch of entries to read than to build a query that selects these entries. Also, the batch gives you precise control over the order in which the entries are returned.
If http:httpMethod is GET or DELETE, the Atom entry SHOULD NOT carry any XML payload for the resource. It only needs to carry the resource id. If it carries an XML payload, it is ignored by the provider.
An individual entry in a batch MUST always correspond to a single resource. The <id> element of a batch entry MUST be a single resource URL; it cannot be a collection URL.
The batch request itself MUST be submitted with a POST.
SData providers that support the batching protocol MUST conform to the rules above.