Fedora Atomic Batch Operations Specification

Atomic Operations

Introduction

Fedora provides factilities by which to conduct multiple operations against a repository in an atomic fashion.

          # Discover the transaction endpoint

          HEAD http://example.org/repo

          200 OK
          Link: <http://example.org/repo/fcr:tx>;
                rel="http://fedora.info/definitions/v4/transaction#endpoint"

          # Begin a transaction

          POST http://example.org/repo/fcr:tx

          201 Created
          Location: http://example.org/repo/fcr:tx/13423c37-2e36-425e-a126-9025e2da7aae
          Link: <http://example.org/repo/fcr:tx/13423c37-2e36-425e-a126-9025e2da7aae/commit;
                rel="http://fedora.info/definitions/v4/transaction#commitEndpoint"

          # Create a new resource within the transaction

          POST http://example.org/repo/container
          Slug: foobar
          Atomic-ID: http://example.org/repo/fcr:tx/13423c37-2e36-425e-a126-9025e2da7aae

          201 Created
          Location: http://example.org/repo/container/foobar
          Atomic-ID: http://example.org/repo/fcr:tx/13423c37-2e36-425e-a126-9025e2da7aae

          # That resource is not visible outside of the transaction

          HEAD http://example.org/repo/container/foobar

          404 Not Found

          # But is visible within the transaction

          HEAD http://example.org/repo/container/foobar
          Atomic-ID: http://example.org/repo/fcr:tx/13423c37-2e36-425e-a126-9025e2da7aae

          200 OK

          # Commit the transaction

          PUT
          http://example.org/repo/fcr:tx/13423c37-2e36-425e-a126-9025e2da7aae/commit

          204 No Content

          # Now the new resource is visible outside the transaction

          HEAD http://example.org/repo/container/foobar

          200 OK

Transaction endpoint

Transactions are created through a transaction endpoint. The transaction endpoint MUST be a resolvable HTTP URI.

A server that supports atomic operations MUST advertise this support by including a Link header in responses to requests for the repository root. The value of this link MUST be the transaction endpoint URI. The rel parameter of this header MUST be http://fedora.info/definitions/v4/transaction#endpoint.

Beginning an atomic series of operations

A client begins an atomic series of requests by sending a POST request to a transaction endpoint.

If the server is able to create the transaction, it MUST respond with a 201 Created HTTP status and MUST include a Location header whose value is a transaction identifier. A transaction identifier MUST be a resolvable HTTP URI.

A server MUST also include a Link header in its response. The value of this link MUST be a commit endpoint. The rel parameter of this header MUST be http://fedora.info/definitions/v4/transaction#commitEndpoint. A commit endpoint MUST be a resolvable HTTP URI.

Adding to an atomic series of operations

A client adds to an atomic batch operation by including an Atomic-ID request header to its request. The value of this header is a transaction identifier.

The effect of the request, if it has one, and if the request is successful, MUST be visible to clients using the same transaction identifier as the value of the Atomic-ID header, as described here, until the series expires or is finished. The effect of the request, if it has one, and if the request is successful, SHOULD NOT be visible to clients not using that transaction identifier. The effect of the request MUST NOT be durable unless and until the series is successfully finished.

If the request is successful, the server MUST include an Atomic-ID response header whose value MUST be the current transaction identifier.

If the transaction identified by the Atomic-ID header is invalid for any reason, the server MUST NOT update any resources, and it MUST respond with a 409 Conflict HTTP status. The server MAY also include more information about the reason for rejecting the request in the response body.

A server MAY choose to reject certain operations it normally supports when it receives those requests with an Atomic-ID. If this is the case, the server MUST respond to those requests with a 403 Forbidden HTTP status. The server MAY also include more infromation about the reason for rejecting the request in the response body.

Expiration

An implementation MAY enforce automatic expiration for an atomic series of requests. If so, the response to any request made as part of the series MUST have a Atomic-Expires header with the HTTP datetime at which the series will expire.

An implementation SHOULD extend the lifetime of a series upon the receipt of any request to resources within the scope of the transaction.

An implementation SHOULD permit extending the lifetime of a series by a POST request to the transaction identifier URI. If an implementation supports extending the lifetime of a series, and is able to successfully update the transaction, it MUST respond with a 204 No Content HTTP status. It MUST also include an Atomic-Expires header in the response with the new HTTP datetime at which the series will expire.

If the server supports extending the lifetime of series in general, but is unable to do so for a particular instance, it MUST respond with a 409 Conflict HTTP status. The server MAY also include more information in the body of the response describing the reason for not extending the lifetime of the transaction.

Committing a series

A client finishes an atomic series of requests by sending a PUT request to the commit endpoint for the transaction.

The effects of all requests in the series MUST become durable and MUST become visible to all clients. The transaction identifier of the series MUST be expired and MUST NOT be reused.

If the server is able to successfully complete this request, it MUST respond with a 2xx-series HTTP status.

If the server is unable to successfully complete this request, it MUST respond with a 409 Conflict HTTP status.

Aborting a series

A client aborts an atomic series of requests by sending a DELETE request to the transaction identifier URI.

The effects of all requests in the series MUST disappear to all clients, and MUST be durably gone. The transaction identifier URI of the series MUST be expired and MUST NOT be reused. In addition, the commit endpoint MUST be expired and MUST NOT be reused.