Transaction safety in RESTful APIs - rest

Question

I wonder how to establish transaction safety in RESTful APIs, where everything is built around single entities.
Example
Database model:
Invoice
Item
User-performed steps in the browser:
Change order number.
Add an item.
Remove an item.
Edit an item.
Requests made:
PATCH/PUT invoice data/order number.
POST item.
DELETE item.
PATCH/PUT item.
Issue
If after any of the requests above an error happens, further calls might mess up the data integrity. Additionally previous requests have to be made undone. E.g. if deleting the item fails, then steps 1 and 2 have to be rewound in order for the overall invoice to be how it was before.
Another problem that might arise is a browser crash, dying internet connection, server failure or whatever.
How can one make sure that certain actions are executed in some kind of transaction to maintain data integrity and safety?

Answer 1

So the thing to remember with REST is the "state transfer" bit. You are not telling the server the steps needed to update a resource, you are telling the server the state the resource should be in after the update, because you have already updated it on the client and are now simply transferring this new state over to the server.
So say you have an Invoice item on the server that looks like this JSON on the server
{
invoice_id: 123,
invoice_description: "Some invoice",
invoice_items: [
{item_id: 10, item_desc: "Large item", order_amount: 34},
{item_id: 11, item_desc: "Small item", order_amount: 400}
]
}
And a user wants to edit that invoice as a single atomic transaction. Firstly they GET the invoice from the server. This essentially says "Give me the current state of the invoice"
GET /invoices/123
The user then edits that invoice anyway they want. They decide the number of large items should be 40 not 34. They decide to delete the small items completely. And finally they decide to add another item of "Extra small" items to the invoice. After the user has edited the invoice the client has the following invoice
{
invoice_id: 123,
invoice_description: "Some invoice",
invoice_items: [
{item_id: 10, item_desc: "Large item", order_amount: 40},
{item_id: 30, item_desc: "Extra small item", order_amount: 5}
]
}
So the client has the invoice in a different state to the server. The user now wants to send this back to the server to be stored, so it PUTs the new state of the invoice to the server.
PUT /invoices/123
which essentially says "Here is the new state of this resource."
Now depending on how fancy you want your validation to be the server can simply accept this new state the invoice is in as it is, or it can do a whole load of validation for each change. How much you want to do is up to you.
You would at the very least want to check that no other client has PUT an updated invoice onto the server while the user was editing this copy of the invoice on their client. You can do this by checking the various headers of the HTTP requests (such as the etag header http://en.wikipedia.org/wiki/HTTP_ETag)
If for any reason the server decides that this update is not valid it simply fails the entire PUT request. This is what gives you transactions in HTTP. A require should either work or fail. If it fails it is the servers responsibility to make sure the resource has not been effected by the failed request. From an implantation point of view on the server you would probably do some validation of the new JSON and then attempt to save the new data to a database within a DB transaction. If anything fails then the database is kept in original state and the user is told that the PUT didn't work.
If the request fails the user should be returned a HTTP status code and response that explains why the PUT require failed. This might be because someone else has edited the invoice while the user was thinking about his changes. It might be because the user is trying to put the invoice into an invalid state (say the user tried to PUT an invoice with no items and this breaks the business logic of the company).
You can of course develop a URI scheme that allows editing of individual items in an invoice, for example
GET /invoices/123/items/10
Would give you the item id 10 from invoice id 123. But if you do this you have to allow the editing of these resources independently of each other. If I delete item 10 by sending the delete command
DELETE /invoice/123/items/10
that action must be an independent transaction. If other requests depend on this you must instead do it as detailed above, by updating the invoice itself in a single request. You should never be able to put the resource into an invalid state through a single HTTP request, or to put it another way it should never require multiple HTTP requests to get the resource into a valid state (and thus never require a string of HTTP requests to work in order to be valid)
Hope that helps

Answer 2

Great answer, thanks a lot. There's just one bit I'm not sure about:
What if the user sends back an updated invoice with a new item that
hasn't got an ID yet, because that is always generated at the server?
AFAIK at least PUT wouldn't be correct here, but POST instead.
However, is that how it's done?
Yes PUT would be wrong here. PUT should be idempotent, which means that you should be able to make multiple PUT requests to a resource and if they are the same request the end result should be the same after all of them.
This makes sense if you think again of state transfer again, doing a PUT of the same state multiple times should still end up with the resource in that state. If I upload a PNG file to a resource 20 times the PNG file should be still the same PNG file as if I just uploaded it once.
So you should not have anything unambiguous in the state that you PUT to the server. If you left out the ID of the item you are essentially saying to the server "As part of this state update create a item". And of course if you run that 10 times you will create 10 new items and the invoice will not be in the same state.
So POST would be better here, and you might want to do that to an "items" end point for clarity if you are just updating the items.
POST /invoices/123/items
[
{item_id: 10, item_desc: "Large item", order_amount: 40},
{item_desc: "Extra small item", order_amount: 5}
]
The server can then return you the state of the invoice's items with the newly created IDs in the body of the response
[
{item_id: 10, item_desc: "Large item", order_amount: 40},
{item_id: 30, item_desc: "Extra small item", order_amount: 5}
]