module 3 - how sword works

The SWORD Course

Module3 How

SWORDworks

Module objectives

• By the end of this module you will:– Know how SWORD works– Understand service documents– Know how to retrieve a service document– Know where to find service documents for

common repository platforms– Know how to perform a deposit– Understand what a package is

How does SWORD work?

• A quick re-cap:– SWORD is a web service that allows deposits to

take place into a repository.

HTTP basics

• There are different methods / verbs that we use when interacting with the web:– GET

• Requests a resource

– POST• Create a new resource

– PUT• Update an existing resource

– DELETE• Delete a resource

– and a few others

HTTP basics

• Whenever a web request is made, the server responds with a code:– 200 OK– 201 CREATED– 400 BAD REQUEST– 404 NOT FOUND– 415 UNSUPPORTED MEDIA TYPE– 501 NOT IMPLEMENTED

SWORD foundations• SWORD is a profile of an existing standard– Atom Publishing Protocol (AtomPub)

• AtomPub is for publishing content to the web

• AtomPub is designed to be extended

• AtomPub is used by other systems:– GData (used by Google Docs etc)– Jangle

SWORD foundations

• SWORD is a profile of an existing standard– Atom Publishing Protocol (AtomPub)

• What does this mean?– SWORD isn’t re-inventing the wheel– AtomPub clients / APIs can be re-used

Two step process

1. Ask the repository’s SWORD interface to describe itself

2. Use that information to prepare and make a deposit

Introducing the service document

• Ask the repository’s SWORD interface to describe itself

– This is done using a Service Document

– A service document describes the contract between a user and a repository: what you must provide and what the repository will do in return

Who can request a Service Document?

• A repository typically protects its service documents using HTTP BASIC Authentication– User provides a username and password

– Service document is customised to the user’s rights– Authentication is normally hidden by a SWORD client

How to request a Service Document

• Request a service document from the repository– GET a service document

– In your browser• It may refuse to display it. Save, then open in a text editor

– Using a SWORD client– Using a tools such as curl / wget

• curl http://username:[email protected]/sword/servicedocument

An example service document <?xml version="1.0" encoding="utf-16"?>

<app:service xmlns:atom="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns:sword="http://purl.org/net/sword/" xmlns:dcterms="http://purl.org/dc/terms/"> <sword:version>1.3</sword:version> <sword:verbose>true</sword:verbose> <sword:noOp>true</sword:noOp> <sword:maxUploadSize>-1</sword:maxUploadSize> <app:workspace> <atom:title type="text">DSpace at My University</atom:title> <app:collection href="http://localhost:8080/sword/deposit/2292/475"> <atom:title type="text">Digitool tifs</atom:title> <app:accept>application/zip</app:accept> <sword:acceptPackaging q="1.0">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging> <sword:collectionPolicy>An explanation of the collection policy of this collection.</sword:collectionPolicy> <sword:mediation>true</sword:mediation> </app:collection> <app:collection href="http://localhost:8080/sword/deposit/2292/473"> <atom:title type="text">Mapped items</atom:title> <app:accept>application/zip</app:accept> <sword:acceptPackaging q="1.0">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging> <sword:collectionPolicy>An explanation of the collection policy of this collection.</sword:collectionPolicy> <sword:mediation>true</sword:mediation> </app:collection> </app:workspace></app:service>

Common Service Document locations

• DSpace:– http://dspace.example.com/sword/servicedocument

• EPrints:– http://eprints.example.com/sword-app/servicedocument

• Fedora– http://fedora.example.com/sword/servicedocument

• IntraLibrary:– http://intralibrary.example.com/IntraLibrary-Deposit/

The second step

• We have retrieved the Service Document• We know where we can deposit• We know what we can deposit• We know what will happen to our deposit

Let’s talk about packaging

• What is a package?– Like a birthday present!

– It has some content in the middle– It comes with a card to describe it (metadata)• Who it is for / who it is from / why it was sent

– It is wrapped up

• Examples of packaging formats– IMSCP– JAR files– .docx files

• Typically zip files, with metadata manifests

• What packaging format does my repository use?– No de-facto packaging format in the repository

world– Implications for interoperability

– METS/SWAP implemented by DSpace / EPrints / Fedora

• METS/SWAP– Zip file– mets.xml manifest– Metadata described in SWAP• Dublin Core elements

The second step

• We have retrieved the Service Document• We know where we can deposit• We know what we can deposit• We know what will happen to our deposit• We have created our deposit package

• We perform the deposit…

Performing a deposit• To perform a deposit:– POST a file to the deposit URL

POST /geography-collection HTTP/1.1Host: myrepository.ac.ukContent-Type: application/zip Authorization: Basic ZGFmZnk6c2VjZXJldA==Content-Length: nnnContent-MD5: [md5-digest]Content-Disposition: filename=MyItem.zipX-Packaging: http://purl.org/net/sword-types/mets/dspace User-Agent: My SWORD Client

Performing a depositHTTP/1.1 201 CreatedDate: Mon, 18 August 2008 14:27:11 GMTContent-Length: nnnContent-Type: application/atom+xml; charset="utf-8”Location: http://myrepository.ac.uk/geography-collection/atom/my_deposit.atom

<?xml version="1.0"?><entry xmlns="http://www.w3.org/2005/Atom" xmlns:sword=http://purl.org/net/sword/>

<title>My Deposit</title><id>info:something:1</id><updated>2008-08-18T14:27:08Z</updated><author><name>jbloggs</name></author><summary type="text">A summary</summary><sword:userAgent> SWORD client</sword:userAgent><generator uri="http://myrepository.ac.uk/engine" version="1.0"/><content type="application/zip" src="http://myrepository.ac.uk/geography-collection/deposit1.zip"/><sword:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging><link rel="edit" href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" />

</entry>

A failed deposit• Receive an error document

– Is also an Atom document

HTTP 1.1 400 Bad Request

<?xml version="1.0" encoding="utf-8"?><sword:error xmlns="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/"

xmlns:arxiv="http://arxiv.org/schemas/atom" href=http://example.org/errors/BadManifest><author> <name>Example repository</name> </author><title>ERROR</title><updated>2008-02-19T09:34:27Z</updated><summary>The manifest could be parsed, but was not valid - no technical metadata was provided.</summary><sword:treatment>processing failed</sword:treatment><link rel="alternate" href="https://example.org/help" type="text/html"/>

</sword:error>

SWORD vs AtomPub

• AcceptPackaging– What packaging formats are accepted

• <sword:acceptPackaging q="1.0">http://purl.org/net/sword-types/METSDSpaceSIP

</sword:acceptPackaging>

– Set during deposit• X-Packaging:

http://purl.org/net/sword-types/METSDSpaceSIP

– In deposit response• <sword:packaging>

http://purl.org/net/sword-types/METSDSpaceSIP</sword:packaging>

SWORD vs AtomPub

• Mediated Deposit– Deposit ‘on-behalf-of’– In service document:• <sword:mediation>true</sword:mediation>

– In HTTP requests:• X-On-Behalf-Of: other-user

SWORD vs AtomPub

• Developer features– NoOp deposit (don’t actually make the deposit):• X-No-Op: true

– Verbose output (longer description)• X-Verbose: true

SWORD vs AtomPub

• Nested Service Documents– Stops a service document getting too large when

representing the structure of a large repository• <sword:service>

http://repo.example.org/science/servicedocument</sword:service>

Questions?

• SWORD email list:– [email protected]– https://lists.sourceforge.net/lists/listinfo/sword-

app-tech

Want to learn more?

• If SWORD is the answer, what is the question? Use of the Simple Web service Offering Repository Deposit protocol– http://dx.doi.org/10.1108/00330330910998057– http://hdl.handle.net/2292/5315

Credits

• This course has been produced by:– Stuart Lewis

• The SWORD project– http://swordapp.org/

• Funded by JISC– http://www.jisc.ac.uk/

• Licence– Creative commons

Photo Credits• Lecture hall: http://www.flickr.com/photos/iamthebestartist/2008790/

module 3 - how sword works

Technology

collection policy

example service document

web service

orgnetswordtypesm explanation

service documentin

service documentknow

service documentask

service documentrequest