RESTful merge and split of resource

Question

I have a REST service that serves Invoice functionality, for example I can create, update and delete an invoice via the REST service.

However I now need to have functionality to split an invoice into several new invoices, i.e. the method needs to create x invoices based on one invoice, and then delete the original invoice in one transaction.

I also need a merge method that does the opposite, i.e. multiple invoices merged into one.

How do I create such architect the RESTful way?

Answer 1

We had a similar issue where we wanted to merge 2 resources. After a long debate we decided that a consumer would POST a merge request resource which contained the 2 resources to be merged. Then after looking at it we decided that there was no need for both the complete source and target resource and instead a POST of just the unique identifier was sufficient. We didn't make the merge request with just the 2 ID's come in the body. It was easier to represent in a URL so that's what we did. The response from the POSTing of a merge request is the merged resource.

I guess I'm not a REST guru enough to tell you this was a good strategy or not, but for us it was a simple solution so we went with it.

Answer 2

When you say that want to implement this functionality in "one transaction" I assume you have already determined that you should combine generation of the new invoices and deletion of the old one, into one API call; which is the correct approach. With web services you do want to reduce chatter and there is probably some business logic on how this functionality will generate the new invoices and delete the old one. So I am assuming when you ask how to architect this in a RESTful way you are wondering which HTTP verb to use (i.e. GET, POST, PUT or DELETE) for this new API method. Usually these verbs map to CRUD type operations in the following manner:

• Create -> POST
• Read -> GET
• Update -> PUT
• Delete -> DELETE

So which verb to use when your function both creates and deletes records. A general rule with REST API's is if there is not a clear mapping to CRUD then use POST if there is a change to the server state and a GET if you are just returning information that does not change the server state. So in this case I would go with a POST.

If you are looking for additional guidance on architecting this please be more specific in what you are looking for and I will try to help.