13.4 Batch Response
SData responds to a batch request with an Atom feed. The entries in the returned feed are the individual responses to the request entries. Our example batch request would generate a response such as:
200 OK
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">
<id>http://www.example.com/sdata/myApp/myContract/-/salesOrders/$batch</id>
<title>Sales Orders Batch</title>
<updated>2008-03-31T13:46:45Z</updated>
<link rel="http://schemas.sage.com/sdata/link-relations/schema"
type="application/xml" title="Schema"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders/$schema?version=5" />
<link rel="http://schemas.sage.com/sdata/link-relations/template"
type="application/atom+xml; type=entry" title="Template"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders/$template" />
<link rel="http://schemas.sage.com/sdata/link-relations/post"
type="application/atom+xml; type=entry" title="Post"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders" />
<link rel="http://schemas.sage.com/sdata/link-relations/service"
type="application/atom+xml; type=feed" title="Service"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders/$service" />
<category scheme="http://schemas.sage.com/sdata/categories"
term="collection" label="Resource Collection"/>
<entry>
<id>http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')</id>
<title>Sales Order 43661</title>
<updated>2008-03-31T13:46:45Z</updated>
<link rel="self" type="application/atom+xml; type=entry" title="Refresh"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')" />
<link rel="edit" type="application/atom+xml; type=entry" title="Edit"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')" />
<category scheme="http://schemas.sage.com/sdata/categories"
term="resource" label="Resource"/>
<content>1553,1035</content>
<http:httpStatus>200</http:httpStatus>
<http:httpMessage>OK</http:httpMessage>
<http:location>http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')</http:location>
<http:httpMethod>POST</http:httpMethod>
<http:etag>2nXz9DZYR2pqmcXi/ZCbYA==</http:etag>
<sdata:payload>
<salesOrder xmlns="http://schemas.sage.com/myContract">
<!-- contents skipped for clarity -->
</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>
<link rel="self" type="application/atom+xml; type=entry" title="Refresh"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')" />
<link rel="edit" type="application/atom+xml; type=entry" title="Edit"
href="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')" />
<category scheme="http://schemas.sage.com/sdata/categories"
term="resource" label="Resource"/>
<content>1553,1035</content>
<http:httpStatus>200</http:httpStatus>
<http:httpMessage>OK</http:httpMessage>
<http:httpMethod>PUT</http:httpMethod>
<http:etag>STFtZgHEkPz7TyH98YEmWA==</http:etag>
<sdata:payload>
<salesOrder xmlns="http://schemas.sage.com/myContract">
<!-- contents skipped for clarity -->
</salesOrder>
</sdata:payload>
</entry>
<!-- more entries -->
</feed>
The entries returned by the batch request are almost identical to the entries that would have been returned by individual requests. The only difference is the presence of http:httpStatus and http:httpMessage in every entry (and http:location for created entries, the http:etag element was already present in the non batch case):
<http:httpStatus>200</http:httpStatus>
<http:httpMessage>OK</http:httpMessage>
<http:httpMethod>POST</http:httpMethod>
<http:location>http://www.example.com/sdata/myApp/myContract/-/salesOrders('43661')</http:location>
<http:etag>2nXz9DZYR2pqmcXi/ZCbYA==</http:etag>
These httpStatus, httpMessage, location and etag elements carry information that would otherwise be transmitted through HTTP headers.
The httpMethod element indicates the operation that had been requested in the batch. It is repeated in the response so that the consumer can process the response without having to match response entries with the corresponding request entries.
The HTTP status for the entire batch (the first line of the response) should be 200, even if all the entries have an error status in their http:httpStatus element (a 4xx or 5xx code). This is because the global status indicates whether or not the provider could understand and process the batch “as a whole”, regardless of the success of the operations on individual entries. The global HTTP status will nevertheless be an error code if the batch feed itself was invalid and could not be understood by the provider, or if a server side error prevented execution of the whole batch.
The response feed MUST contain the same number of entries as the request feed, and the responses should be in the same order, so that the consumer can easily match them to the individual requests. If the provider encounters an error in the middle of a batch, it MUST set the global HTTP status to 200 and return the same number of entries. In this case, the unprocessed entries MUST carry a 5xx http:httpStatus code to indicate that the server could not process them.
The sdata:diagnosis XML payload MAY be used to give details about errors and warnings in individual response entries, or it can be used to simply provide information. As a general rule, all the SData mechanisms that are available for CRUD operations on individual entries are also available in batch mode.
Delete operations are handled slightly differently than when sent individually. This is because individual DELETE requests don’t return an Atom entry as the resource doesn’t exist any more. Inside a batch, they generate an Atom entry in the response feed. This Atom entry carries the id of the deleted resource but it doesn’t contain any XML payload for the resource. It also carries the http:httpStatus, http:httpMessage and http:httpMethod elements.
SData providers that support the batching protocol MUST conform to the rules above