Comments on: REST APIs for Batch Operations

By: Tapestry and Restlet : unl33t

Tapestry and Restlet : unl33t — Tue, 12 Jan 2010 21:36:35 +0000

[...] certainly has a couple points of ambiguity, for example batching, but there are options here with various [...]

By: L. Daniel Burr

L. Daniel Burr — Wed, 17 Sep 2008 02:05:24 +0000

I know the REST camp debates this issue frequently, but in my own applications I just made the decision to support a “transaction” resource; I POST to obtain a transaction id; I PUT the set of operations to be processed in said transaction. Done.

Admittedly, this doesn’t work for everyone, but it has worked like a charm for my own use cases, and it certainly can work well for the fruit-fly example above.

By: Rhys Ulerich

Rhys Ulerich — Tue, 16 Sep 2008 23:25:43 +0000

This was a hotly debated/heavily discussed topic between me and a former officemate while doing some SOAP/WSDL API design. Mike wrote it up quite well: http://www.michaelgilfix.com/techblog/2007/02/25/web-service-interface-design
The API design pattern was used in a high-throughput SOAP-over-HTTP building block underneath telecommunications software.

- Rhys

By: Liz

Liz — Tue, 16 Sep 2008 02:20:29 +0000

I don’t have anything technical to add, but I thought I’d drop a comment anyway just to say that your post made me smile because my roommate studies fruit flies. If you ever need to catch some, I’ve learned some of her lab techniques for escapees, and I could demonstrate with photos.

By: Gavin Terrill

Gavin Terrill — Tue, 16 Sep 2008 01:48:05 +0000

REST + Batch don't play well right now.

By: Adam Goucher

Adam Goucher — Tue, 16 Sep 2008 01:18:40 +0000

This might be a clash between Rails and what I think I may know about REST, but…

Single
/api/fly/id, GET
/api/fly/new, POST
/api/fly/id, DELETE

Batch:
/api/flies, GET, {id, id, …}
/api/flies, POST,

The plurality of the name gives it context. It also forces the caller to think about the usage and the access method.

-adam

By: rgz

rgz — Tue, 16 Sep 2008 00:33:39 +0000

This shows what’s wrong with REST, a web api is not like a library but rather a resource like a database server. While I urge you to forgo REST purity, I suggest you forgo it with style. Considering you update objects PUTting to “/api/fly/id” it makes sense to batch update by PUTting to “/api/fly/id1,id3,id5-id8,id9″ basically adding range semantics to REST.

What about it?

By: Kevin Teague

Kevin Teague — Mon, 15 Sep 2008 23:39:54 +0000

REST creator Roy T. Fielding recently wrote on his blog (http://roy.gbiv.com/untangled/):

“Web architects must understand that resources are just consistent mappings from an identifier to some set of views on server-side state. If one view doesn’t suit your needs, then feel free to create a different resource that provides a better view (for any definition of “better”). These views need not have anything to do with how the information is stored on the server, or even what kind of state it ultimately reflects. It just needs to be understandable (and actionable) by the recipient.”

URLs such as /fly/1, /fly/2, etc. that have a one-to-one mapping from URL to entity are good as a starting point because they are widely understood, but don’t think that by creating another resource to handle batch input for transactional and performance reasons in anyway violates REST principles.

By: Dethe Elza

Dethe Elza — Mon, 15 Sep 2008 23:02:39 +0000

This may be obvious, but the poster child for RESTful APIs is the Atom Publishing Protocol (http://bitworking.org/projects/atom/rfc5023.html). While that spec doesn’t explicitly tell how to PUT multiple items, you can extrapolate from their lists, which GET multiple items. Simply provide a url that expects a list of items rather than single items. It can then return a list of the item ids/urls for GET or POST (if editable) as needed.

By: Jeremy Handcock

Jeremy Handcock — Mon, 15 Sep 2008 21:05:06 +0000

Hi Greg,

I’m not sure I fully understand the proposed batch API. How will clients know which flies were updated? What happens if an update fails? How does it solve the problem of possible request timeouts?

Regardless of the architectural style (REST, XML/RPC, etc.), have you considered an asynchronous API? From what I’ve read in your post, it sounds like you might be better off that way. The client PUTs a list of flies, it receives a requestId, and then the client polls the server to check the status of the batch request. When the batch request status is complete, the client can get a report that indicates what fly updates succeeded/failed (if it cares about such things).

So the API would look something like this:

PUT /api/flies {id_0, name_0, genome_0}, {id_1, name_1, genome_1}, …}
RESPONSE {requestId}

GET /api/batchRequest/requestId
RESPONSE {status}, ie. IN_PROGRESS, COMPLETE, FAILED, etc.

GET /api/batchReport/requestId
RESPONSE {report}

Of course you could maintain your original single-fly synchronous API if there are situations where you need it.