Skip to content

Examples

Jump to bottom
Ralf Claussnitzer edited this page Mar 30, 2015 · 7 revisions

Note: Hostnames in the examples are made up.

Requesting the Service Document

After installing Qucosa SWORD File Handler and connecting it to a Fedora Commons 3 repository, you should be able to ask for the configured SWORD service document. Assuming a Fedora user sword with password sword requesting the service document can be done via curl similar to this:

$ curl -i -usword:sword http://qucosa.app.dev:8080/sword/servicedocument

This should then output the service document. Here an example of the standard configuration of https://github.com/qucosa/qucosa-vagrant:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/atomsvc+xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 13 Feb 2015 13:34:06 GMT

<?xml version="1.0" encoding="UTF-8"?>
<app:service xmlns:app="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:sword="http://purl.org/net/sword/">
   <sword:version>1.3</sword:version>
   <sword:verbose>true</sword:verbose>
   <sword:noOp>true</sword:noOp>
   <app:workspace>
      <atom:title type="text">Fedora SWORD Workspace</atom:title>
      <app:collection href="http://qucosa.app.dev/sword/qucosa:all">
         <atom:title type="text">Qucosa General Collection</atom:title>
         <app:accept>application/vnd.qucosa.mets+xml</app:accept>
         <sword:acceptPackaging q="0.9">http://www.loc.gov/METS/</sword:acceptPackaging>
         <sword:collectionPolicy>This collection accepts any deposit on behalf of the `sword` user</sword:collectionPolicy>
         <dcterms:abstract>This is a collection of all Qucosa objects</dcterms:abstract>
         <sword:mediation>true</sword:mediation>
         <sword:treatment>Preservation actions may occur on submited deposits</sword:treatment>
      </app:collection>
   </app:workspace>
</app:service>

Ingesting an object

In the same way one could do an ingest via curl by issuing a POST request on a collection. Here we ingest a METS document from an XML file:

$ curl -i -XPOST -usword:sword --data-binary @mets.xml -H'Content-Type:application/vnd.qucosa.mets+xml' 'qucosa.vagrant.dev:8080/sword/qucosa:all'

The returned SWORD document tells us about the details of the ingest and the URL of the ingested deposit:

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://qucosa.app.dev/sword/qucosa:all/qucosa:2
Content-Type: application/atom+xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Sat, 14 Feb 2015 12:29:23 GMT

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/">
   <atom:id>qucosa:2</atom:id>
   <atom:author>
      <atom:name>sword</atom:name>
   </atom:author>
   <atom:content type="application/vnd.qucosa.mets+xml" src="http://qucosa.app.dev:8080/fedora/get/qucosa:2/upload"/>
   <atom:generator uri="http://qucosa.app.dev/sword" version="1.3"/>
   <atom:link href="http://qucosa.app.dev/sword/qucosa:all/qucosa:2" rel="edit" hreflang="en"/>
   <atom:published>2015-02-14T12:29:23Z</atom:published>
   <atom:rights type="text"/>
   <atom:summary type="text"/>
   <atom:title type="text">Qucosa: Quality Content of Saxony</atom:title>
   <atom:updated>2015-02-14T12:29:23Z</atom:updated>
   <sword:treatment>Preservation actions may occur on submited deposits</sword:treatment>
   <sword:verboseDescription>Your deposit was added to the repository with identifier qucosa:2. Thank you for depositing.</sword:verboseDescription>
   <sword:noOp>false</sword:noOp>
   <sword:userAgent>curl/7.35.0</sword:userAgent>
</atom:entry>

Updating the deposit

By using the HTTP PUT method on the URL the example above generated, we can update the deposited object. Let's add another file that we have on disk. Note that "on disk" means that this path is accessible by the SWORD service. In this case the METS doesn't has to be complete (valid according to METS schema). It is sufficient to have the <mets:fileGrp> element specified properly:

<?xml version="1.0" encoding="UTF-8"?>
<mets:mets xmlns:mets="http://www.loc.gov/METS/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" OBJID="qucosa:1"
           xsi:schemaLocation="http://www.loc.gov/METS/ http://www.loc.gov/standards/mets/mets.xsd">
    <mets:fileSec>
        <mets:fileGrp USE="ORIGINAL">
            <mets:file ID="ATT-2" MIMETYPE="image/png">
                <mets:FLocat xmlns:xlin="http://www.w3.org/1999/xlink" USE="TEMPORARY"
                    LOCTYPE="URL" xlin:href="file:/tmp/A.png" xlin:title="Picture"/>
            </mets:file>
        </mets:fileGrp>
    </mets:fileSec>
</mets:mets>

There are two interesting things about the <mets:file> element here: First, the attribute USE="TEMPORARY" in <mets:FLocat> makes the Qucosa File Handler delete the file on successful ingest; This is useful for temporary uploaded files. Second, the content URL in the xlin:href attribute has the URL scheme file:; This tells the Qucosa File Handler to upload a file from the filesystem to Fedora instead of just passing the URL to reference content (in this case Fedora itself would download on ingest).

With the appropriate curl command we tell the SWORD service to update the previously ingested object and add another datastream ATT-2 to the corresponding Fedora object:

$ curl -i -XPUT -usword:sword --data-binary @mets_update.xml -H'Content-Type:application/vnd.qucosa.mets+xml' 'qucosa.vagrant.dev:8080/sword/qucosa:all/qucosa:2'

The SWORD service returns a message very similar to the initial ingest result:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Location: http://qucosa.app.dev/sword/qucosa:all/qucosa:2
Content-Type: application/atom+xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Sat, 14 Feb 2015 13:11:13 GMT

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/">
   <atom:id>qucosa:2</atom:id>
   <atom:author>
      <atom:name>sword</atom:name>
   </atom:author>
   <atom:content type="application/vnd.qucosa.mets+xml" src="http://qucosa.app.dev:8080/fedora/get/qucosa:2/upload"/>
   <atom:generator uri="http://qucosa.app.dev/sword" version="1.3"/>
   <atom:link href="http://qucosa.app.dev/sword/qucosa:all/qucosa:2" rel="edit" hreflang="en"/>
   <atom:published>2015-02-14T13:11:14Z</atom:published>
   <atom:rights type="text"/>
   <atom:summary type="text"/>
   <atom:title type="text"/>
   <atom:updated>2015-02-14T13:11:14Z</atom:updated>
   <sword:treatment>Preservation actions may occur on submited deposits</sword:treatment>
   <sword:verboseDescription>Your deposit was added to the repository with identifier qucosa:2. Thank you for depositing.</sword:verboseDescription>
   <sword:noOp>false</sword:noOp>
   <sword:userAgent>curl/7.35.0</sword:userAgent>
</atom:entry>
  • See the Test Resources for more XML examples, especially on how to delete specific datastreams.

Mediation or Depositing on behalf of another user

The request contains authentication information to authorize ingest requests. This ingest agent credentials don't always match the actual owner of the deposited object in the repository. This is where the SWORD deposit mediation comes in.

By specifying an special header, e.g. X-On-Behalf-Of:slub, the deposited object will now belong to the Fedora user slub and not to the user agent that authenticated for the request (e.g. sword for the previous examples).

Deleting a deposit

Last but not least the HTTP DELETE method can be used to delete a deposited object from the repository:

$ curl -i -usword:sword -XDELETE http://qucosa.vagrant.dev:8080/sword/qucosa:all/qucosa:2

This responds with a RESTful HTTP/1.1 204 No Content if the request was successful. Note that the object doesn't actually get purged from the repository, instead the Qucosa File Handler sets the object's state to DELETED. This behavior makes the DELETE method idempotent. So executing it again will not result in HTTP/1.1 404 Not Found but in HTTP/1.1 204 No Content again.

Getting Started

How it works

Clone this wiki locally