Module 3 - How SWORD Works

The SWORD Course
Module3
HowSWORD
works

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
Ask the repository’s SWORD interface to describe itself
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:password@example.com/sword/servicedocument

An example service document
<?xml version="1.0" encoding="utf-16"?><app:servicexmlns: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:collectionhref="http://localhost:8080/sword/deposit/2292/475"> <atom:title type="text">Digitooltifs</atom:title> <app:accept>application/zip</app:accept> <sword:acceptPackagingq="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:collectionhref="http://localhost:8080/sword/deposit/2292/473"> <atom:title type="text">Mapped items</atom:title> <app:accept>application/zip</app:accept> <sword:acceptPackagingq="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 whatwe 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 whatwe 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.1
Host: myrepository.ac.uk
Content-Type: application/zip
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
Content-MD5: [md5-digest]
Content-Disposition: filename=MyItem.zip
X-Packaging: http://purl.org/net/sword-types/mets/dspace
User-Agent: My SWORD Client

Performing a deposit
HTTP/1.1 201 Created
Date: Mon, 18 August 2008 14:27:11 GMT
Content-Length: nnn
Content-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:errorxmlns="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 vsAtomPub
AcceptPackaging
What packaging formats are accepted
<sword:acceptPackagingq="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 vsAtomPub
Mediated Deposit
Deposit ‘on-behalf-of’
In service document:
<sword:mediation>true</sword:mediation>
In HTTP requests:
X-On-Behalf-Of: other-user

SWORD vsAtomPub
Developer features
NoOp deposit (don’t actually make the deposit):
X-No-Op: true
Verbose output (longer description)
X-Verbose: true

SWORD vsAtomPub
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:
sword-app-tech@lists.sourceforge.net
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

by SWORD Project on Jul 23, 2010

Accessibility

Categories

Upload Details

Usage Rights

Statistics

Module 3 - How SWORD Works Presentation Transcript