2PC Transactions Submission 1 - REST-* Transactions

Overview

Specification of how to model 2PC transactions as RESTful resources. We do not discuss whether or not transactions and REST are a good architectural fit suffice to say that there are proponents for both sides of the argument. Certainly it is worth pointing out that if a system cannot be made reliable then it can be of only limited utility. That said it is a worthwhile exercise to show how a REST based system can be made reliable.

Disclaimer: Although the following protocol is viable it was in fact written over 8 years ago by another community member, namely Mark Little. Things have moved on since then and we do plan to re-evaluate the specification.

The protocol makes use of three resource types:

A participant is an entity responsible for ensuring that changes to a resource can be driven through a 2PC protocol. It must ensure that changes to resources are recoverable in the presence of failures and that changes are durable and isolated from other changes. Participants are analogous to Resource Managers in the X/Open XA specification.
The transaction coordinator is responsible for enlisting participants in the transaction and for driving participants through a 2PC protocol.
A recovery coordinator provides the mechanism to support recovery after failure of participants. Participants are allowed to change their URLs provided they notify the coordinator.

A client is the entity that wishes to manipulate resources within the context of a transaction. It may or may not be modeled as a resource.

Protocol Description

All actors are modeled as URLs, the idea being that doing PUT, DELETE, GET and POST to the various URLs will control how a transaction makes progress and how changes to resources are processed reliably (ie obey ACID properties).

The transaction coordinator address is <scheme>://<authority>/transaction-coordinator. In the following this address is referred to as TC;
The recovery coordinator address is <scheme>://<authority>/recovery-coordinator. In the following this address is referred to as RC;
A participant address is unspecified but the semantics of PUT, DELETE, GET and POST to the address are specified. In the following this address is referred to as P-URL.

POST is used to create resources, PUT will modify a resource and GET retrieves a resource:

a successful PUT returns status code 200 (OK) and any XML data in the body;
a successful POST returns status code 201 (created) and a Location header containing the URI of the newly created resource;
a successful GET returns status code 200 (OK) and any XML data in the body;
DELETE is not used and therefore returns 401 (Unauthorized)

URL	GET	PUT	POST
TC	Return all transactions (1)
TC/recovery	Return all recovering transactions (2)
TC/active	Return all active transactions (3)
TC/begin?clientId={id}			Start a transaction (with default timeout) returns url TC/{txid} which is deleted after the timeout or after completion (any HTTP method relating to {txid} thereafter returns 404)
TC/begin?clientId={id}&timeout={timeout}			Start a transaction (with specified timeout) returns url TC/{txid} which is deleted after the timeout or after completion (any HTTP method relating to {txid} thereafter returns 404)
TC/{txid}/commit		Trigger commit (4)
TC/{txid}	Return the transaction status (5)
TC/{txid}?P-URL={url}		Enlist url in the transaction returning a unique resource for that participant of the form RC/{RecCoordId}	401
RC/{RecCoordId}	Return the participant URL	Replace the participant URL (7)	401
P-URL	Return the status of this participant. A status is any of the statuses returned by prepare and commit
P-URL/prepare	400	401	The participant prepares any work done in the context of the transaction (see note 6). Returns a status URL indicating the outcome: P-URL/prepare-ok P-URL/prepare-readonly P-URL/prepare-notok A 404 response indicates that the participant has rolled back.
P-URL/commit	400	401	The participant commits any work done in the context of the transaction (see note 6). Returns a status URL indicating the outcome: P-URL/committed P-URL/rolledback P-URL/heuristic (8) A 404 response indicates that the participant has already terminated.
P-URL/rollback	400	401	The participant rolls back any work done in the context of the transaction (see note 6). Returns a status URL indicating the outcome: P-URL/rolledback P-URL/heuristic (8) A 404 response indicates that the transaction has already terminated.
P-URL/forget	Returns the status if a heuristic exists and 404 otherwise	401	The participant forgets any heuristic decision

Notes

The body of the response contains an XML document exposing a list of transactions.
A recovering transaction is one that is completing but one or more participants have failed to respond either because of network failure or a server has failed.
An active transaction is one which has not completed and is not recovering.
Upon successful termination, the URL is implicitly deleted. An HTTP OK response means the transaction either committed or rolled back. If the client wishes to discriminate between the two outcomes he must register a participant with the transaction. If some participants committed whilst others aborted then the coordinator remembers this heuristic outcome.
The status is only returned if the transaction is still active or is recovering. The body of the response contains an XML document exposing the status of the transaction.
Participant URLs must be unique with respect to the transaction but is otherwise unconstrained. This URL can be asked to prepare and, if it were not for this restriction, the participant would have no means of knowing which transaction was being prepared.
This operation means that participants can tell the recovery coordinator that they have moved in the event of a failure. Implementation Note: After failure the recovery system will periodically attempt to contact in doubt participants. If the participant has moved it will get HTTP status 404 (Not Found). In this case the recovery subsystem issues a GET on RC/{RecCoordId} if the participant has moved. If it gets a different URL back it will switch over to using the new one.
If the participant has already committed when asked to rollback or vice-versa the participant must remember the decision until told to forget it.

Version:

Forward-Compensation Submission 1	Sep 18
reststar_icon_64x.png	Aug 28
2PC Transactions Submission 1	Aug 26