/
README
360 lines (244 loc) · 14.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
=======================================================================
= SSS - Simple SWORD Server
=======================================================================
= Author: Richard Jones
=======================================================================
Introduction
============
The Simple SWORD Server is a reference implementation of the draft SWORD 2.0 specification. It is designed to respond
to requests as if it were a real SWORD 2.0 server, although under the hood it is a simple file store which carries out
minimal processing on the content it works with.
Prerequisites
=============
SSS depends on web.py and lxml, so you will need to easy_install both of these before proceeding. You will need to have installed libxml2 and libxslt1.1 for lxml to install.
Quick Start
===========
NOTE: using CherryPy out of the box does not support HTTP 1.1 (due to a bug), so you will need to issue requests with HTTP 1.0. This is a nuisance, so for uses other than using CURL it is recommended to run SSS behind Apache, as described further down...
To start SSS using CherryPy, place sss.py in suitable directory of its own and start it with
python sss.py
This will start the webserver at
http://localhost:8080/
Note that SSS automatically creates a data store in the directory in which the sss.py file is located so this should
be done in a suitable directory. To start the server on an alternative port (e.g. 8443) start it with
python sss.py 8443
Configuration
=============
SSS has a configuration object which can be modified to change some aspects of its behaviour. Open sss.py for
editing and find the Configuration object; each of the options available to you is documented inline.
If you are running this using the Quick Start above, you can leave the configuration as-is and everything should work. If you are deploying SSS under Apache, you will need to change the configuration object from CherryPyConfiguration to ApacheConfiguration which can be done at the end of the file.
Deployment Under Apache
=======================
In order to get HTTP 1.1 support, it is necessary to deploy SSS under Apache (CherryPy does not support HTTP 1.1 at this point due to a bug)
To do this, you can follow the instructions at:
http://webpy.org/cookbook/mod_wsgi-apache
When setting up your httpd.conf file, to allow file uploads to use Transfer-Encoding: chunked, and to ensure authorization credentials are forwarded, you will need to set up the configuration as follows:
LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so
WSGIScriptAlias /sss /path/to/SSS/sss.py
WSGIPassAuthorization On
Alias /sss/static /path/to/SSS/static/
AddType text/html .py
<Directory /path/to/SSS/>
WSGIChunkedRequest On
Order deny,allow
Allow from all
</Directory>
Note this sets an explicit location for the wsgi_module (required for Ubuntu, YMMV on other platforms), and adds the WSGIChunkedRequest to the correct context.
Requests to the server with CURL
================================
This section describes a series of CURL requests which utilise each part of the SWORD web service
Notice that for POST and PUT requests we use HTTP 1.0 for the curl requests. This is because the CherryPy web server
which SSS operates under natively doesn't properly respond to those requests (although the functionality of the server
is unaffected). You may find that programming against the SSS will require you to explicitly use HTTP 1.0 - this should
NOT be considered a requirement for SWORD 2.0.
Authentication
--------------
To see the various authentication results, try the following requests on the service document. By default SSS has the
following user details:
- user: sword
- password: sword
- On-Behalf-Of: obo
curl -i http://sword:sword@localhost:8080/sd-uri
Successful authentication without an On-Behalf-Of user
curl -i -H "X-On-Behalf-Of: obo" http://sword:sword@localhost:8080/sd-uri
Successful authentication with an On-Behalf-Of user
curl -i http://localhost:8080/sd-uri
No Basic Auth credentials supplied, 401 Unauthorised response
curl -i http://sword:drows@localhost:8080/sd-uri
Incorrect password, 401 unauthorised response
curl -i http://drows:sword@localhost:8080/sd-uri
Incorrect user, 401 unauthorised response
curl -i -H "X-On-Behalf-Of: bob" http://sword:sword@localhost:8080/sd-uri
Correct user but invalid On-Behalf-Of user, 401 unauthorised response
All subsequent requests can be done with an X-On-Behalf-Of header; no further examples will be provided
Get the Service Document
------------------------
HTTP: GET on SD-URI
curl -i http://sword:sword@localhost:8080/sd-uri
This returns the Service Document with the configured number of collections listed
Deposit some new content
------------------------
HTTP: POST on Col-URI
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
sword:sword@[Col-URI]
This posts the example.zip file to the Col-URI with the filename "example.zip", and specifying that it is a zip
file. Without the X-Packaging header this will be interpreted as a default SWORD package. Col-URI should be obtained
from the Service Document.
This should return an HTTP status of 201 Created, and a Deposit Receipt
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-In-Progress: true"
sword:sword@[Col-URI]
This should return an HTTP status of 202 Accepted, and a Deposit Receipt
curl -i --http1.0 --data-binary "@multipart.dat"
-H 'Content-Type: multipart/related; boundary="===============0670350989=="'
-H "MIME-Version: 1.0"
sword:sword@[Col-URI]
This will mimic an Atom Multipart deposit and will create two items in the container: atom.xml and example.xml (prefixed
with the current timestamp). This should return an HTTP status of 201 Created and a Deposit Receipt. You may add
-H "X-In-Progress: true" to get a 202 Accepted back instead, as above.
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-Packaging: http://purl.org/net/sword/package/METSDSpaceSIP"
sword:sword@[Col-URI]
This is an example using a different package format for the example.zip. At the moment the ingest packager in SSS
will simply leave this package as it is, without attempting to unpack it
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "Content-MD5: 2b25f82ba67284461d4a481d7a06dd28"
sword:sword[Col-URI]
This is an example where we provide the correct MD5 checksum for the item, just to demonstrate that this works with
or without the checksum. See the section below on errors to supply incorrect checksums.
List the contents of a Collection
---------------------------------
HTTP: GET on Col-URI
curl -i sword:sword@[Col-URI]
This will return an Atom Feed where each atom:entry refers to a collection in the specified collection. This is
implemented only for the sake of convenience, so is not a full Feed; instead it just contains an atom:link element
containing the href to the Edit-URI for that Collection
Get a representation of the container (Media Resource)
------------------------------------------------------
HTTP: GET on the Cont-URI or EM-URI
curl -i [EM-URI]
Get the default dissemination package from the server. In this case curl fills in the Accept header for us with "*/*".
This will return an application/zip file of all the content in the container. Notice that this request does not
require authentication, as SSS models this as the public face of the content for the purposes of example.
FIXME: this method of content negotiation is under debate, although the SSS currently supports it
curl -i -H "Accept: application/zip;swordpackage=http://www.swordapp.org/package/default" [EM-URI]
Explicitly request a zip file in the standard sword package format (which is, incidentally, a plain zip file)
curl -i -H "Accept: application/zip" [EM-URI]
Explicitly request an ordinary zip file of the content (which happens to be no different from the standard sword package)
curl -i -H "Accept: text/html" [EM-URI]
Explicitly request the HTML representation of the Media Resource. This will return a 302 Found HTTP header with a
Location header which points to the HTML representation
curl -i -H "Accept: application/vnd+msword" [EM-URI]
Generate a 415 Unsupported Media Type error
Overwrite the existing Media Resource with a new one
----------------------------------------------------
HTTP: PUT on EM-URI
curl -i -X PUT --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
sword:sword@[EM-URI]
This will replace all the existing content in the container identified with the EM-URI with the attached example.zip
file. The package format is interpreted as the default sword package. It will return a 201 Created and a Deposit
Receipt
curl -i -X PUT --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-In-Progress: true"
sword:sword@[EM-URI]
This will do the same as above, but will return a 202 Accepted indicating that the update has been accepted into the
server, but has not yet been processed (for the purposes of example, obviously; it doesn't make any difference to
what actually happens on the server).
FIXME: this is not how AtomPub works, it instead says this should return a 200 - the jury is still out for SWORD on this
curl -i -X PUT --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-Suppress-Metadata: true"
sword:sword@[EM-URI]
This would do the same as above but tells the server not to update the metadata of the item based on this deposit. SSS
does not implement metadata updates for default packages which are not multipart, so this won't have any actual effect,
but it is a valid request.
curl -i -X PUT --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-Packaging: http://purl.org/net/sword/package/METSDSpaceSIP"
sword:sword@[EM-URI]
An example of the same as above but with the X-Packaging header passed in.
Delete the content but not the container
----------------------------------------
HTTP: DELETE on EM-URI
curl -i -X DELETE sword:sword@[EM-URI]
This deletes all the content from the store, but not the container itself, and returns a 200 OK and a Deposit Receipt
Get a representation of the container
-------------------------------------
HTTP: GET on Edit-URI
curl -i sword:sword@[Edit-URI]
This retrieves the Edit-URI in its default format, which is as a copy of the Deposit Receipt - an atom entry document
curl -i -H "Accept: application/rdf+xml" sword:sword@[Edit-URI]
This gives us the pure RDF/XML statement from the repository
curl -i -H "Accept: application/atom+xml;type=entry" sword:sword@[Edit-URI]
This explicitly requests the Edit-URI in its atom entry form, which is the same as the default format
Update a container by adding new content to the existing content
----------------------------------------------------------------
HTTP: POST on Edit-URI
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
sword:sword@[Edit-URI]
This adds the example.zip file to the server (notice that the Content-Disposition gives it the same name - SSS will
localise the names on receipt to avoid overwriting existing files) without removing any of the existing content. This
will return a 201 Created (or if you add the X-In-Progress header a 202 Accepted) and the Deposit Receipt.
curl -i --http1.0 --data-binary "@multipart.dat"
-H 'Content-Type: multipart/related; boundary="===============0670350989=="'
-H "MIME-Version: 1.0"
sword:sword@[Edit-URI]
This will mimic an Atom Multipart deposit and will create two items in the container: atom.xml and example.xml (prefixed
with the current timestamp). The atom.xml will overwrite any existing atom.xml file in this case, while the
example.zip will just be added under a localised name. This should return an HTTP status of 201 Created and a Deposit
Receipt. You may add -H "X-In-Progress: true" to get a 202 Accepted back instead, as above.
curl -i --http1.0 --data-binary "@multipart.dat"
-H 'Content-Type: multipart/related; boundary="===============0670350989=="'
-H "MIME-Version: 1.0"
-H "X-Suppress-Metadata: true"
sword:sword@[Edit-URI]
This version of the request, with the X-Suppress-Metadata header set will do the same as above but it will not
attempt to extract any metadata from the atom.xml file as it would have done otherwise.
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-Packaging: http://purl.org/net/sword/package/METSDSpaceSIP"
sword:sword@[Edit-URI]
Delete the container and all its contents
-----------------------------------------
HTTP: DELETE on Edit-URI
curl -i -X DELETE sword:sword@[Edit-URI]
This will remove all the content from the container followed by the container itself. It will return a 204 No Content
response with no response body.
Generating Errors
-----------------
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-Packaging: http://purl.org/net/sword/package/error"
sword:sword[Col-URI]
Generates an ErrorContent error response on depositing a package whose package type doesn't match the X-Packaging
header
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "Content-MD5: 1234567890"
sword:sword[Col-URI]
Generate an error for a mismatch between the checksum and the supplied checksum header, resulting in a 412 Precondition
Failed error.
curl -i --http1.0 --data-binary "@example.zip"
-H "Content-Disposition: filename=example.zip"
-H "Content-Type: application/zip"
-H "X-In-Progress: whatever"
sword:sword[Col-URI]
Generate a Bad Request error by passing an illegal value to X-In-Progress, resulting in a 400 Bad Request response