Module 3 - How SWORD Works

1. The SWORD Course Module3 HowSWORD works

2. 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

3. How does SWORD work? A quick re-cap: SWORD is a web service that allows deposits to take place into a repository.

4. 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

5. 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

6. 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

7. 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

8. Two step process Ask the repository’s SWORD interface to describe itself Use that information to prepare and make a deposit

9. 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

10. 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

11. 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

12. 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>

19. 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/

20. 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

21. 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

22. Let’s talk about packaging Examples of packaging formats IMSCP JAR files .docx files Typically zip files, with metadata manifests

23. 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

24. Let’s talk about packaging METS/SWAP Zip file mets.xml manifest Metadata described in SWAP Dublin Core elements

25. 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…

26. 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

27. 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>

28. 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>

29. 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>

30. 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

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

32. 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>

33. Questions? SWORD email list: sword-app-tech@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sword-app-tech

34. 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

35. 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

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

Module 3 - How SWORD Works

Recommended

Recommended

More Related Content

Similar to Module 3 - How SWORD Works

Similar to Module 3 - How SWORD Works (20)

Recently uploaded

Recently uploaded (20)

Module 3 - How SWORD Works