The SWORD Course<br />Module3<br />HowSWORD<br />works<br />
Module objectives<br />By the end of this module you will:<br />Know how SWORD works<br />Understand service documents<br ...
How does SWORD work?<br />A quick re-cap:<br />SWORD is a web service that allows deposits to take place into a repository...
HTTP basics<br />There are different methods / verbs that we use when interacting with the web:<br />GET<br />Requests a r...
HTTP basics<br />Whenever a web request is made, the server responds with a code:<br />200 OK<br />201 CREATED<br />400 BA...
SWORD foundations<br />SWORD is a profile of an existing standard<br />Atom Publishing Protocol (AtomPub)<br />AtomPub is ...
SWORD foundations<br />SWORD is a profile of an existing standard<br />Atom Publishing Protocol (AtomPub)<br />What does t...
Two step process<br />Ask the repository’s SWORD interface to describe itself<br />Use that information to prepare and mak...
Introducing the service document<br />Ask the repository’s SWORD interface to describe itself<br />This is done using a Se...
Who can request a Service Document?<br />A repository typically protects its service documents using HTTP BASIC Authentica...
How to request a Service Document<br />Request a service document from the repository<br />GET a service document<br />In ...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
An example service document<br />           <?xml version="1.0" encoding="utf-16"?><app:servicexmlns:atom="http://www.w3.o...
Common Service Document locations<br />DSpace:<br />http://dspace.example.com/sword/servicedocument<br />EPrints:<br />htt...
The second step<br />We have retrieved the Service Document<br />We know where we can deposit<br />We know whatwe can depo...
Let’s talk about packaging<br />What is a package?<br />Like a birthday present!<br />It has some content in the middle<br...
Let’s talk about packaging<br />Examples of packaging formats<br />IMSCP<br />JAR files<br />.docx files<br />Typically zi...
Let’s talk about packaging<br />What packaging format does my repository use?<br />No de-facto packaging format in the rep...
Let’s talk about packaging<br />METS/SWAP<br />Zip file<br />mets.xml manifest<br />Metadata described in SWAP<br />Dublin...
The second step<br />We have retrieved the Service Document<br />We know where we can deposit<br />We know whatwe can depo...
Performing a deposit<br />To perform a deposit:<br />POST a file to the deposit URL<br />POST /geography-collection HTTP/1...
Performing a deposit<br />HTTP/1.1 201 Created<br />Date: Mon, 18 August 2008 14:27:11 GMT<br />Content-Length: nnn<br />C...
A failed deposit<br />Receive an error document<br />Is also an Atom document<br />HTTP 1.1 400 Bad Request<br /><?xml ver...
SWORD vsAtomPub<br />AcceptPackaging<br />What packaging formats are accepted<br /><sword:acceptPackagingq="1.0">http://pu...
SWORD vsAtomPub<br />Mediated Deposit<br />Deposit ‘on-behalf-of’<br />In service document:<br /><sword:mediation>true</sw...
SWORD vsAtomPub<br />Developer features<br />NoOp deposit (don’t actually make the deposit):<br />X-No-Op: true<br />Verbo...
SWORD vsAtomPub<br />Nested Service Documents<br />Stops a service document getting too large when representing the struct...
Questions?<br />SWORD email list:<br />sword-app-tech@lists.sourceforge.net<br />https://lists.sourceforge.net/lists/listi...
Want to learn more?<br />If SWORD is the answer, what is the question? Use of the Simple Web service Offering Repository D...
Credits<br />This course has been produced by:<br />Stuart Lewis<br />The SWORD project<br />http://swordapp.org/<br />Fun...
Photo Credits<br />Lecture hall: http://www.flickr.com/photos/iamthebestartist/2008790/<br />
Upcoming SlideShare
Loading in...5
×

Module 3 - How SWORD Works

5,134

Published on

Module 3 of ’The SWORD Course’.

For further information see http://swordapp.org/

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
5,134
On Slideshare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
70
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Module 3 - How SWORD Works

  1. 1. The SWORD Course<br />Module3<br />HowSWORD<br />works<br />
  2. 2. Module objectives<br />By the end of this module you will:<br />Know how SWORD works<br />Understand service documents<br />Know how to retrieve a service document<br />Know where to find service documents for common repository platforms<br />Know how to perform a deposit<br />Understand what a package is<br />
  3. 3. How does SWORD work?<br />A quick re-cap:<br />SWORD is a web service that allows deposits to take place into a repository.<br />
  4. 4. HTTP basics<br />There are different methods / verbs that we use when interacting with the web:<br />GET<br />Requests a resource<br />POST<br />Create a new resource<br />PUT<br />Update an existing resource<br />DELETE<br />Delete a resource<br />and a few others<br />
  5. 5. HTTP basics<br />Whenever a web request is made, the server responds with a code:<br />200 OK<br />201 CREATED<br />400 BAD REQUEST<br />404 NOT FOUND<br />415 UNSUPPORTED MEDIA TYPE<br />501 NOT IMPLEMENTED<br />
  6. 6. SWORD foundations<br />SWORD is a profile of an existing standard<br />Atom Publishing Protocol (AtomPub)<br />AtomPub is for publishing content to the web<br />AtomPub is designed to be extended<br />AtomPub is used by other systems:<br />GData (used by Google Docs etc)<br />Jangle<br />
  7. 7. SWORD foundations<br />SWORD is a profile of an existing standard<br />Atom Publishing Protocol (AtomPub)<br />What does this mean?<br />SWORD isn’t re-inventing the wheel<br />AtomPub clients / APIs can be re-used<br />
  8. 8. Two step process<br />Ask the repository’s SWORD interface to describe itself<br />Use that information to prepare and make a deposit<br />
  9. 9. Introducing the service document<br />Ask the repository’s SWORD interface to describe itself<br />This is done using a Service Document<br />A service document describes the contract between a user and a repository: what you must provide and what the repository will do in return<br />
  10. 10. Who can request a Service Document?<br />A repository typically protects its service documents using HTTP BASIC Authentication<br />User provides a username and password<br />Service document is customised to the user’s rights<br />Authentication is normally hidden by a SWORD client<br />
  11. 11. How to request a Service Document<br />Request a service document from the repository<br />GET a service document<br />In your browser<br />It may refuse to display it. Save, then open in a text editor<br />Using a SWORD client<br />Using a tools such as curl / wget<br />curl http://username:password@example.com/sword/servicedocument<br />
  12. 12. An example service document<br /> <?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> <br />
  13. 13. An example service document<br /> <?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> <br />
  14. 14. An example service document<br /> <?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> <br />
  15. 15. An example service document<br /> <?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> <br />
  16. 16. An example service document<br /> <?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> <br />
  17. 17. An example service document<br /> <?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> <br />
  18. 18. An example service document<br /> <?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> <br />
  19. 19. Common Service Document locations<br />DSpace:<br />http://dspace.example.com/sword/servicedocument<br />EPrints:<br />http://eprints.example.com/sword-app/servicedocument<br />Fedora<br />http://fedora.example.com/sword/servicedocument<br />IntraLibrary:<br />http://intralibrary.example.com/IntraLibrary-Deposit/<br />
  20. 20. The second step<br />We have retrieved the Service Document<br />We know where we can deposit<br />We know whatwe can deposit<br />We know what will happen to our deposit<br />
  21. 21. Let’s talk about packaging<br />What is a package?<br />Like a birthday present!<br />It has some content in the middle<br />It comes with a card to describe it (metadata)<br />Who it is for / who it is from / why it was sent<br />It is wrapped up<br />
  22. 22. Let’s talk about packaging<br />Examples of packaging formats<br />IMSCP<br />JAR files<br />.docx files<br />Typically zip files, with metadata manifests<br />
  23. 23. Let’s talk about packaging<br />What packaging format does my repository use?<br />No de-facto packaging format in the repository world<br />Implications for interoperability<br />METS/SWAP implemented by DSpace / EPrints / Fedora<br />
  24. 24. Let’s talk about packaging<br />METS/SWAP<br />Zip file<br />mets.xml manifest<br />Metadata described in SWAP<br />Dublin Core elements<br />
  25. 25. The second step<br />We have retrieved the Service Document<br />We know where we can deposit<br />We know whatwe can deposit<br />We know what will happen to our deposit<br />We have created our deposit package<br />We perform the deposit…<br />
  26. 26. Performing a deposit<br />To perform a deposit:<br />POST a file to the deposit URL<br />POST /geography-collection HTTP/1.1<br />Host: myrepository.ac.uk<br />Content-Type: application/zip <br />Authorization: Basic ZGFmZnk6c2VjZXJldA==<br />Content-Length: nnn<br />Content-MD5: [md5-digest]<br />Content-Disposition: filename=MyItem.zip<br />X-Packaging: http://purl.org/net/sword-types/mets/dspace<br />User-Agent: My SWORD Client<br />
  27. 27. Performing a deposit<br />HTTP/1.1 201 Created<br />Date: Mon, 18 August 2008 14:27:11 GMT<br />Content-Length: nnn<br />Content-Type: application/atom+xml; charset="utf-8”<br />Location: http://myrepository.ac.uk/geography-collection/atom/my_deposit.atom<br /><?xml version="1.0"?><br /><entry xmlns="http://www.w3.org/2005/Atom" xmlns:sword=http://purl.org/net/sword/><br /> <title>My Deposit</title><br /> <id>info:something:1</id><br /> <updated>2008-08-18T14:27:08Z</updated><br /> <author><name>jbloggs</name></author><br /> <summary type="text">A summary</summary><br /> <sword:userAgent> SWORD client</sword:userAgent><br /> <generator uri="http://myrepository.ac.uk/engine" version="1.0"/><br /> <content type="application/zip"src="http://myrepository.ac.uk/geography-collection/deposit1.zip"/><br /> <sword:packaging>http://purl.org/net/sword-types/mets/dspace</sword:packaging><br /> <link rel="edit" href="http://www.myrepository.ac.uk/geography-collection/atom/my_deposit.atom" /><br /></entry> <br />
  28. 28. A failed deposit<br />Receive an error document<br />Is also an Atom document<br />HTTP 1.1 400 Bad Request<br /><?xml version="1.0" encoding="utf-8"?><br /><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><br /> <author> <name>Example repository</name> </author><br /> <title>ERROR</title><br /> <updated>2008-02-19T09:34:27Z</updated><br /> <summary>The manifest could be parsed, but was not valid - no technical metadata was provided.</summary><br /> <sword:treatment>processing failed</sword:treatment><br /> <link rel="alternate" href="https://example.org/help" type="text/html"/><br /></sword:error> <br />
  29. 29. SWORD vsAtomPub<br />AcceptPackaging<br />What packaging formats are accepted<br /><sword:acceptPackagingq="1.0">http://purl.org/net/sword-types/METSDSpaceSIP</sword:acceptPackaging> <br />Set during deposit<br />X-Packaging: http://purl.org/net/sword-types/METSDSpaceSIP<br />In deposit response<br /><sword:packaging>http://purl.org/net/sword-types/METSDSpaceSIP</sword:packaging><br />
  30. 30. SWORD vsAtomPub<br />Mediated Deposit<br />Deposit ‘on-behalf-of’<br />In service document:<br /><sword:mediation>true</sword:mediation><br />In HTTP requests:<br />X-On-Behalf-Of: other-user<br />
  31. 31. SWORD vsAtomPub<br />Developer features<br />NoOp deposit (don’t actually make the deposit):<br />X-No-Op: true<br />Verbose output (longer description)<br />X-Verbose: true<br />
  32. 32. SWORD vsAtomPub<br />Nested Service Documents<br />Stops a service document getting too large when representing the structure of a large repository<br /><sword:service> http://repo.example.org/science/servicedocument</sword:service><br />
  33. 33. Questions?<br />SWORD email list:<br />sword-app-tech@lists.sourceforge.net<br />https://lists.sourceforge.net/lists/listinfo/sword-app-tech<br />
  34. 34. Want to learn more?<br />If SWORD is the answer, what is the question? Use of the Simple Web service Offering Repository Deposit protocol<br />http://dx.doi.org/10.1108/00330330910998057<br />http://hdl.handle.net/2292/5315<br />
  35. 35. Credits<br />This course has been produced by:<br />Stuart Lewis<br />The SWORD project<br />http://swordapp.org/<br />Funded by JISC<br />http://www.jisc.ac.uk/<br />Licence<br />Creative commons<br />
  36. 36. Photo Credits<br />Lecture hall: http://www.flickr.com/photos/iamthebestartist/2008790/<br />
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×