Question

Let’s say I have a trip planning application, and each trip is composed of “path” resources (representing a route to be driven, for example) composed as a series of points. I can CRUD these resources using requests like so (just an example):

POST /trips/1234/paths

<Path>
  <Point>32,32</Point>
  <Point>32,34</Point>
  <Point>34,34</Point>
</Path>

DELETE /trips/1234/paths/3

Now consider that I want to be able to split a Path into two paths. In the aobve example, I might want to pick the point (32,34) to split on, which would result in two paths – one ends at that point, one starts at that point. What this means is that a single action creates two new resources, and simultaneously, deletes another (the path that was split).

So if the path in the example above was the only path in the system, and I split it with a single call, the system would now contain two new paths and the original would be gone. Example:

<Path>
  <Point>32,32</Point>
  <Point>32,34</Point>
</Path>

<Path>
  <Point>32,34</Point>
  <Point>34,34</Point>
</Path>

I’m struggling with how this would be handled RESTfully. How does one handle calls that result in multiple resources being created/modified/deleted and communicate that to the caller?

I can definitely figure it out with multiple calls (two POSTs to create the new paths and a DELETE to remove the original), but I want this to be a single call.

Answer 1

I would try to implement it like @Darrel Miller’s answer yet make it a little less RPCish.
The idea is to create a PathSplit resource that guides the client each step of the way to complete the transaction. This way the client knows the result of each step and knows hows to back out if there is an error along the way.

Something like this should do the trick.

POST /pathsplit HTTP/1.1
Content-Type: application/vnd.acme.pathsplit+xml
<pathsplit xmlns="http://schema.acme.com">
  <path>
    <id>123</id>
  </path>
  <splitpoint>
      <point>32,34</point>
  </splitpoint>
</pathsplit>

=>
HTTP/1.1 201 Created
Content-Type: application/vnd.acme.pathsplit+xml
Location:
  http://acme.com/pathsplit/11

<pathsplit xmlns="http://schema.acme.com">
  <path>
    <id>123</id>
  </path>
  <splitpoint>
      <point>32,34</point>
  </splitpoint>
  <newpaths>
    <Path>
      <Point>32,32</Point>
      <Point>32,34</Point>
    </Path>
    <Path>
      <Point>32,34</Point>
      <Point>34,34</Point>
    </Path>
    <createuri>http://acme.org/trips/paths</createuri>
  </newpaths>
  <oldpath>
    <uri>http://acme.org/trips/paths/123</uri>
  </oldpath>
    <status>in-progress</status>
    <pathscreated>0</pathscreated>
</pathsplit>

With something like this the client can always GET the pathsplit resource to see what actions to take. In this example it would create both new paths following the createuri link and sending a POST request for each new path in newpaths. The server updates the status as each new resource is created.

Once the status has pathscreated of 2, the client can delete the old path by following the uri and sending the DELETE verb. Finally, it would delete the pathsplit resource, thus indicating that everything succeeded.

At every step along the way, in case of an error, or in the all too common case of a network outage, the client always knows what state the server is in and what state the transaction is in.

The pathsplit resource remains available as long as the transaction hasn’t completed.
The client also has the option of reverting a transaction that has not yet completed. Again, since it knows what operations have completed successfully and which haven’t, it can always back out the transaction.