Upload
sword-project
View
4.938
Download
2
Tags:
Embed Size (px)
DESCRIPTION
Module 3 of ’The SWORD Course’. For further information see http://swordapp.org/
Citation preview
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>
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>
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>
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>
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>
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>
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
Let’s talk about packaging
• Examples of packaging formats– IMSCP– JAR files– .docx files
• Typically zip files, with metadata manifests
Let’s talk about packaging
• 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
Let’s talk about packaging
• 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/