Difference between revisions of "Sword API"

Revision as of 18:39, 4 November 2013

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.

Endpoints

Create a new transfer

HTTP POST to http://localhost/api/v2/transfer
used to start a new transfer in Archivematica
return HTTP 200 OK if already created, otherwise 201 if accepted (see example later in page)
HTTP GET lists transfers that have been submitted
Needs to return metadata about the transfer

Example

POST http://localhost/api/v2/transfer/create HTTP/1.1
Host: localhost
Authorization: Archivematica_API api_key="[api key]", username="[archivematica username]"
Content-Length: [content length]
Content-Type: application/atom+xml;type=entry
In-Progress: true
On-Behalf-Of: [islandora user]
Slug: [suggested identifier]

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    <title>[aip-name]</title>
    <id>[aip-id]</id>
    <author>[islandora user]</author>
    <summary>[optional description of transfer]</summary>
    <updated>[current timestamp]</updated>
</entry>

Each Transfer will have a set of endpoints available after creation.

Transfer Details

redirect to Edit-IRI
used to get basic info about a Transfer with HTTP GET
can update basic info using HTTP PUT
can allow deletion with HTTP DELETE
follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]
example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a

EM-IRI

Edit-Media IRI
used to add new objects to an existing transfer
follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media
example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/media

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.

example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit

SE-IRI

State-IRI

used to retrieve status of transfer
implemented as rdf document
example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/status
should be able to subscribe like RSS feed

Rough notes

Step 1) Add Content

POST a single Fedora Object to Col-IRI

http://localhost/api/v2/transfer/create/

described here: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html#protocoloperations_creatingresource_entry

You post will look like the sample below (content in [] should be replaced with appropriate values). Instead of dcterms embedded in the atom entry document, you would embed the fedora mets file for this object.

The <id> tag inside the <entry> should contain the AIP id (generated from user input or based on the collection).

To add additional content to the same AIP, you can either POST another

POST http://localhost/api/v2/transfer/create/ HTTP/1.1
Host: localhost
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: application/atom+xml;type=entry
In-Progress: true
On-Behalf-Of: [archivematica-user]
Slug: [suggested identifier]

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <title>Title</title>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2005-10-07T17:17:08Z</updated>
    <author><name>Contributor</name></author>
    <summary type="text">The abstract</summary>

    <!-- some embedded metadata -->
    <dcterms:abstract>The abstract</dcterms:abstract>
    <dcterms:accessRights>Access Rights</dcterms:accessRights>
    <dcterms:alternative>Alternative Title</dcterms:alternative>
    <dcterms:available>Date Available</dcterms:available>
    <dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
    <dcterms:contributor>Contributor</dcterms:contributor>
    <dcterms:description>Description</dcterms:description>
    <dcterms:hasPart>Has Part</dcterms:hasPart>
    <dcterms:hasVersion>Has Version</dcterms:hasVersion>
    <dcterms:identifier>Identifier</dcterms:identifier>
    <dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
    <dcterms:publisher>Publisher</dcterms:publisher>
    <dcterms:references>References</dcterms:references>
    <dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
    <dcterms:source>Source</dcterms:source>
    <dcterms:title>Title</dcterms:title>
    <dcterms:type>Type</dcterms:type>

</entry>

The response back will be in the following form:

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/"
        xmlns:dcterms="http://purl.org/dc/terms/">

    <title>My Deposit</title>
    <id>info:something:1</id>
    <updated>2008-08-18T14:27:08Z</updated>
    <summary type="text">A summary</summary>
    <generator uri="http://www.myrepository.ac.uk/sword-plugin" version="1.0"/>

    <!-- the item's metadata -->
    <dcterms:abstract>The abstract</dcterms:abstract>
    <dcterms:accessRights>Access Rights</dcterms:accessRights>
    <dcterms:alternative>Alternative Title</dcterms:alternative>
    <dcterms:available>Date Available</dcterms:available>
    <dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
    <dcterms:contributor>Contributor</dcterms:contributor>
    <dcterms:description>Description</dcterms:description>
    <dcterms:hasPart>Has Part</dcterms:hasPart>
    <dcterms:hasVersion>Has Version</dcterms:hasVersion>
    <dcterms:identifier>Identifier</dcterms:identifier>
    <dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
    <dcterms:publisher>Publisher</dcterms:publisher>
    <dcterms:references>References</dcterms:references>
    <dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
    <dcterms:source>Source</dcterms:source>
    <dcterms:title>Title</dcterms:title>
    <dcterms:type>Type</dcterms:type>

    <!-- 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>

To finalize an AIP

blank HTTP POST to the SE-IRI for the AIP: in this example, the POST would look like:

POST http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a/ HTTP/1.1
Host: localhost
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: application/atom+xml;type=entry
In-Progress: false

response will be HTTP 200/OK or 400/Error

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.

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/