Difference between revisions of "Sword API"
(→EM-IRI) |
|||
Line 9: | Line 9: | ||
* HTTP POST to http://localhost/api/v2/transfer/ | * HTTP POST to http://localhost/api/v2/transfer/ | ||
* used to start a new transfer in Archivematica | * used to start a new transfer in Archivematica | ||
+ | * return HTTP 200 OK if already created | ||
* HTTP GET lists transfers that have been submitted | * HTTP GET lists transfers that have been submitted | ||
+ | * Needs to return metadata about the transfer | ||
Each Transfer will have a set of endpoints available after creation. | Each Transfer will have a set of endpoints available after creation. |
Revision as of 18:57, 23 October 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
- HTTP GET lists transfers that have been submitted
- Needs to return metadata about the transfer
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]/edit-media/
- example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit-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.
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
- 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.