Fedora Atomic Batch Operations Specification

Unofficial Draft

Latest editor's draft:
https://fcrepo.github.io/fcrepo-specification-atomic-operations/
Test suite:
https://github.com/fcrepo/fcrepo-tcks
Editor:
Peter Eichman (University of Maryland)
Former editors:
Ben Armintor (Columbia University)
Aaron Birkland (Johns Hopkins)
Sergio Fernández (Redlink)
Tom Johnson (Digital Public Library of America)
Nick Ruest (York University)
Rob Sanderson (The Getty Trust)
Bethany Seeger (Amherst College)
Adam Soroka (University of Virginia)
Simeon Warner (Cornell University)
Joshua Westgard (University of Maryland)
Jared Whiklo (University of Manitoba)
Andrew Woods (DuraSpace)
Repository:
Github
Issues
Commits

This document is licensed under a Creative Commons Attribution 4.0 License.

Abstract

Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Terminology

transaction endpoint
a URI that supports operations to create a new transaction
transaction identifier
a URI that uniquely identifies a transaction, and which may be used to perform operations on that transaction
commit endpoint
a URI that a client uses to indicate that they are finishing a transaction and they wish their changes to become durable

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.

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.

Acknowledgments