AtomServer, Batching Details

• See the Atom Publishing Protocol Reference for further information about the elements of the feed itself. Note that we do not exhaustingly document this information ourselves,  because we are using Atom entirely as dictated by the standard.
• See the AtomServer Protocol Basics document for general information about communicating with the AtomServer service.
  

Contents

• General Information
  
• Submitting a batch request
• Writing a batch operations feed
• Insert operations
  
• Update operations
• Delete operations
• Handling status codes
• Example batch operations and status feed
• Additional Resources
  

General Information

For example, the following feed includes three operations (a delete and two updates -- one an insert and one an update)

The service will perform as many of the requested changes as possible and return status information that you can use to evaluate the success or failure of each operation.

The service attempts to execute each of the operations within a batch, even if some of the operations included in the batch do not succeed. Note that this means that, internal to AtomServer, the operations are batched to the database. Thus, batch processing in AtomServer can very much improve overall performance, and is strongly recommended if you need to publish many entries at once.

There are several points to notice when looking at the example above;

• Batches are submitted and returned as a <feed>. This means that you can use mostly standard Atom syntax (<feed>, <entry>, etc) when composing a batch operations request.
  
• You must provide a special XML element <asbatch:operation type="insert|update|delete"/> for each <entry> that you submit for batch processing. This may be either per Entry or per Batch.
  
• You must provide the atomserver asbatch namespace on the <feed> element (i.e <feed xmlns:asbatch="http://atomserver.org/namespaces/1.0/batch"> )
• You must provide the atomserver namespace on the <entry> element (i.e <entry xmlns:as="http://atomserver.org/namespaces/1.0/"> )
• You must provide a "edit link" to identify which entry to operate on. (e.g. <link href="/myserver/v1/widgets/acme/92348.en.xml/2" rel="edit"/>) This is consistent with all other AtomServer usage. The edit link is the only guaranteed way to edit an entry in AtomServer. This link should contain the correct revision number to satisfy optimistic concurrency expectations.

Submitting a batch request

A batch request should be sent as an HTTP PUT to a AtomServer batch URL, which is simply the Feed URL with "/$batch" appended to it. So, for example, if you wanted to send a set of batch operations to the "widgets/acme" feed, then you would PUT to the following URL;

Writing a batch operations feed

A batch operations feed contains a list of entries to insert, update, or delete. Each operation is defined by a <asbatch:operation type="insert|update|delete"/> element. How these these operations work directly reflects how AtomServer works for PUT, POST, and DELETE of individual Entries.

• PUT.  In AtomServer you can submit both inserts and updates using a HTTP PUT (a, so called, Lazy Insert), and this behavior is, of course, reflected in the batch processing API. For either PUT operation - an update or insert - you must submit an "edit link" that represents an Entry URL. (e.g. <link href="/myserver/v1/widgets/acme/92348.en.xml/2" rel="edit"/>).
• POST. You can also request a batch insert operation that reflects a RESTful HTTP POST, and in this case the Entry Id is generated by AtomServer. Here you must provide an "edit link" that represents a "Feed URL. (e.g <link href="/myserver/v1/widgets/acme" rel="edit"/>).
  
• DELETE. To request a batch delete operation that reflects a HTTP DELETE, you must submit an "edit link" that represents an Entry URL. (e.g. <link href="/myserver/v1/widgets/acme/92348.en.xml/2" rel="edit"/>).

The operation element may be a direct child of a <feed> element, a direct child of any of the Entries in the Feed, or both. When included in an Entry, it specifies the operation to execute for that specific Entry. When included in the Feed, this element specifies the default operation to execute on any Entries that do not have a <asbatch:operation/> element.

When neither the Entry nor the Feed specifies an operation, the default operation is update.

Applications may not apply multiple operations to the same entry in a single batch feed. The results would be indeterminate if you specified multiple operations for the same entry, therefore, an Exception is thrown and you will recieve a 400 HTTP response code in the <asbatch:status/> element.

Operations are NOT necessarily performed in the order listed in the feed - operations are partitioned into two groups - updates and deletes - and each group is executed in a single batch operation to the database.  For this reason, you may not submit multiple operations on the same entry in the same batch, and doing so will produce an error for all duplicates. The first Entry in a duplicate set will be processed, and all others will result in errors.

It is important to note that AtomServer will attempt to process all Entries in the batch, and will return all Entries in the same order it received them. If any errors occured, those Entries will be returned along with all others, and will simply be flagged as errors. The status element will indicate the error that occured and a short description of the reason (e.g. <asbatch:status code="400" reason="Bad Request::....." /> )

By default, the number of entries in the XML batch operations feed that you send to the server may not exceed 15 for "full entries" and 100 for "link entries" (look here for definitions of these terms).  This restriction allows AtomServer to protect itself from excessive feeds. Note, the numbers shown here are the default values, and a AtomServer Workspace can be configured with alternate values.

Insert operations

An insert operation is denoted as follows:

In AtomServer, an insert operation is equivalent to either PUTing or POSTing a new Entry. Which of these occurs depends upon the "edit link" that is provided. If an Entry URL is provided within the "edit link"; a PUT equivalent occurs. And if a Feed URL is provided within the "edit link"; a POST equivalent occurs. This exactly matches the behavior of AtomServer in general. 

When the insert operation succeeds, the entire Entry content is returned, with an updated document id field. And you will receive a <asbatch:status code="201"/> element. 

Here is an example of a successful POST insert Request:

Here is an example of a Response to a successful insert request:

Note that the <asbatch:operation> is returned with type="insert" when an insert occurs.

Update operations

An update operation is denoted as follows:

In AtomServer, a PUT operation can result in either an insert and an update operation, and not surprisingly AtomServer allows this same behavior in batch operations.

When the update operation succeeds, the entire entry content is returned, with an updated document id field. If an insert occurred, you will receive a <asbatch:status code="201"/> element. And if an update occurred, you will receive a <asbatch:status code="200"/> element.

Here is an example of a successful insert request:

Here is an example of a response to a successful update request:

Note that the <asbatch:operation> is returned with type="insert" when an insert occurs, and type="update" when an update occurs

Delete operations

A delete operation is equivalent to executing a DELETE on the URL referenced by by the entry's <next> element. For a delete operation, you only need to send a valid <link ... rel="next/> to delete the entry. Any other information you provide in elements that aren't in the asbatch: namespace will be ignored. When the operation succeeds, a <batch:status code="200"/> element will be returned.

Here is an example of a delete request:

Here is an example of a successful response:

Handling status codes

Status codes are expressed by the following element:

Each entry in the response feed contains one <asbatch:status> element. This element describes what happened while executing the operation. It mimics the HTTP response that would have been sent if the operation had been sent individually, rather than as part of a batch feed.

You need to check the <asbatch:status> element of each entry in the response to find out whether the associated operation was successfully processed. The code="n" attribute contains a AtomServer status code.

Status descriptions

The reason="reason" attribute of the <asbatch:status> element contains a more verbose explanation of the operation's status.

Content type

The content-type="type" attribute of the <asbatch:status> element contains the MIME type of the data contained in the <batch:status> element. This corresponds to the Content-Type header of an HTTP status response. This attribute is optional.

When the content type is set, the body of the <asbatch:status> element describes what went wrong while processing the entry.

Example batch operations and status feed

Here is a batch operations feed that could be sent to the server. This feed requests that the server delete two entries and modify two new entries.

PUT   http://myserver.com/myserver/v1/widgets/acme/$batch

Let's assume that the two "updates" worked, but one of the two deletions failed. In this case, the batch status feed might look like the following. Note that the Entries are returned in exactly the same order that they appear in the Batch Request.

Additional resources