Sword API

From Archivematica
Revision as of 04:16, 5 November 2013 by Jhs (talk | contribs)
Jump to navigation Jump to search

Overview

One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a Sword 2.0 API. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.

As described elsewhere on this wiki, "the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)".

The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers.

  1. Create Transfer - set the name and other metadata about a Transfer
  2. Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata
  3. Finalize Transfer - indicates that the Transfer is ready to start processing.

Transfers created through the Dashboard (the Archivematica web based user interface) can be manipulated through this api as well, allowing content from 3rd party applications to be combined with manually created Transfers.

Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.

Endpoints

List existing transfers

  • HTTP Get to the Collection IRI (defined by default as: /api/v2/transfer)
  • optional filters via get parameters (not yet implemented)

Create a new transfer

  • used to start a new transfer in Archivematica
  • HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v2/transfer)

Possible HTTP Response Codes

  • HTTP 200 OK - transfer already exists
  • HTTP 201 Created - tranfer has been accepted
  • HTTP 412 Precondition Failed - required metadata missing or invalid

Valid requests will receive a Sword Deposit Receipt in the body of the response.

Required HTTP Headers The HTTP POST must include certain specific http headers.

Required by http 1.1 specification:

  • Host: Must be set to archivematica host name.
  • Content-Length: Must be set to the length of the atom entry document.
  • Content-Type: Must be set to "application/atom+xml;type=entry".

Required by Archivematica.

  • Authorization: Must include the api key and username assigned by Archivematica.

Required by SWORD 2.0 protocol:

  • In-Progress: Must be set to "true"

Optional in SWORD 2.0 protocol:

  • On-Behalf-Of: not implemented by Archivematica
  • Slug: not implemented by Archivematica

Required in Body The Body of the request must be a valid Atom Entry Document. The required fields in an Atom Entry Document are:

    • title: used as the transfer name
    • id: used as an accession id
    • author: used as the source of acquisition
    • summary: not implemented yet. Could be used in the future as a description for the Transfer
    • updated: should be set to the current timestamp.

Example Example HTTP POST request: 

POST /api/v2/transfer HTTP/1.1
Host: localhost
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"
Content-Length: 213
Content-Type: application/atom+xml;type=entry
In-Progress: true

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    <title>Test Transfer 1</title>
    <id>2013-0001</id>
    <author>John Doe</author>
    <summary></summary>
    <updated>2013-11-04T11:00:00Z</updated>
</entry>

Example Response: 

201 Created
Location: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a

<entry xmlns="http://www.w3.org/2005/Atom"
        xmlns:sword="http://purl.org/net/sword/">
       
    <title>Test Transfer</title>
    <id>2013-0001</id>
    <author>
    <updated>2008-08-18T14:27:08Z</updated>
    <summary type="text">A summary</summary>
    
    <!-- EM-IRI -->
    <link rel="edit-media" href="http://localhost/api/v2/transfer/edit/1225c695-cfb8-4ebb-aaaa-80da344efa6a" />

    <!-- Edit-IRI -->
    <link rel="edit" href="http://localhost/api/v2/transfer/edit/1225c695-cfb8-4ebb-aaaa-80da344efa6a" />

    <!-- SE-IRI -->
    <link rel="http://purl.org/net/sword/terms/add" href="http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a" />

    <!-- State-IRI -->
    <link rel="http://purl.org/net/sword/terms/statement"
            type="application/atom+xml;type=feed"
            href="http://localhost/api/v2/transfer/feed/1225c695-cfb8-4ebb-aaaa-80da344efa6a" />
    <link rel="http://purl.org/net/sword/terms/statement"
            type="application/rdf+xml"
            href="http://localhost/api/v2/transfer/rdf/1225c695-cfb8-4ebb-aaaa-80da344efa6a" />
</entry>

Add Files to a Transfer

  • POST a METS file to the SE-IRI (listed below).
  • HTTP headers are required similar to Create Transfer call (above).
  • Body must include a valid Atom Entry document, that has METS embedded inside it.
  • It is possible to also POST the actual file, (using Multipart in the Content-Type header).
  • If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer.

Finalize a Transfer

  • POST with no body to the SE-IRI
  • set In-Progress HTTP header to : false
  • This will tell Archivematica that no further content will be added or removed from the Transfer.
  • Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.

Example 

POST http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a/ HTTP/1.1
Host: localhost
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"
Content-Length: 0
Content-Type: application/atom+xml;type=entry
In-Progress: false

response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized or does not yet exist).

Get Status of Transfer

To check Status:

GET the State-IRI in this example:

GET http://localhost/api/v2/transfer/feed/1225c695-cfb8-4ebb-aaaa-80da344efa6a/ HTTP/1.1

response will include: 

<sword:state href="http://localhost/api/v2/transfer/feed/1225c695-cfb8-4ebb-aaaa-80da344efa6a/">
    <sword:stateDescription>The item has passed through the workflow and is now archived</sword:stateDescription>
</sword:state>

the list of possible descriptions is not finalized.

Additional Details

Transfer Details

EM-IRI

An HTTP POST to the em-iri for a transfer should include a file as the body (may not be supported in v2, return "not supported" HTTP status)

An HTTP GET should return a list of files in the transfer

An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.

Edit-IRI

The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI.

This would be used to update metadata about a transfer, such as the transfer name.

SE-IRI

State-IRI

Example session

Below is an example session using curl to manipulate the API. In the example a transfer is created, a file is added to it, and it is finalized.

NOTE: While this is in development, change the URL list "mock_object_content_urls" in src/dashboard/src/components/api/view.py to working URL(s). 

# create new transfer
curl -v -H "In-Progress: true" -d "some METS XML" --request POST http://localhost/api/v2/transfer
# response XML includes endpoint for adding addition files, etc.
  
# add another file to the transfer
curl -v -H "Content-Disposition: attachment; filename=horse.jpg" --request POST --data-binary "@horse.jpg" http://localhost/api/v2/transfer/03ce11a5-32c1-445a-83ac-400008894f78/media
  
# finalize transfer and approve processing
curl -v -H "In-Progress: false" --request POST http://localhost/api/v2/transfer/03ce11a5-32c1-445a-83ac-400008894f78

You might, at some point, want to list the transfers that have been started. The following curl command will do so. 

 # list transfers that have been created by the API
 curl -v http://localhost/api/v2/transfer

If you're working on a transfer and want to list what files are included in it, the following curl command will list them. 

 # list files in transfer
 curl -v http://localhost/api/v2/transfer/03ce11a5-32c1-445a-83ac-400008894f78/media

If you've started a transfer, but decide not to proceed, you can delete the transfer. The following curl command shows an example. 

 curl -v -XDELETE http://localhost/api/v2/transfer/5ac7819a-9ad8-4e59-b9e8-fb0ccf7e167b/03ce11a5-32c1-445a-83ac-400008894f78
Retrieved from "https://wiki.archivematica.org/index.php?title=Sword_API&oldid=9089"