SKUA interfacesWe expect to design a RESTful HTTP interface, plus a Java/Python/whatever interface which sits on top of that, and provides both a convenience layer to applications, and some higher-level abstractions. More details soon. First version of the API diagram: 
HTTP interfaceFrom Kona, with additions by Norman. During Iteration2, Kona implemented this interface in a dummy servlet for testing purposes, and Norman implemented an initial SAC based on Quaestor. The interface for the latter is in a WADL file in the repository. TODO: align these two implementations, and identify a stable URL for the interface. | Endpoint | Method | Input | Output | Comment | In DummyServlet yet? | In Quaestor SAC yet? | | sacstore.org/johnnysac | PUT | SAC metadata as RDF | Status 201, or 409 Conflict if the SAC exists | Create a SAC at a multiSAC. Thre are authorisation issues... What to do if metadata not present? Dummy Servlet returning Bad Request | Yes | Yes | | sacstore.org/johnnysac | POST | Claim RDF | Status 201 with the new claim id in the HTTP Location: header | | Yes | yes | | sacstore.org/johnnysac | POST | SPARQL query | Query response | | No - dummy method needed? | Yes | | sacstore.org/johnnysac | GET | | Retrieves all SAC RDF | not sure what to do here | Not yet | Yes | | sacstore.org/johnnysac?query=xxx | GET | | Query response | url-encoded SPARQL query | No - dummy method needed? | yes | | sacstore.org/johnnysac?metadata | GET | | simply returns the creation metadata | SAC metadata | To be done | yes | | sacstore.org/johnnysac | DELETE | | 200 if OK, 404 if SAC not found | Deletes the SAC | Yes | yes | | sacstore.org/johnnysac/claim/XXX | PUT | Claim RDF | Status 201 if claim didn't exist, Status 200 if it did, with the claim id in the HTTP Location: header | Returned claim ID is same as method URL. This method always overwrites any pre-existing claim with that ID. (i.e. an update method) | Needs update | Yes, but always returning status 204 on success, or 404 if the claim doesn't exist -- ie, not a create method Comment suggests this IS a create method - what do we want? | | sacstore.org/johnnysac/claim/XXX | POST | Claim RDF | If claim XXX doesn't exist, Status 201 with the new claim id in the HTTP Location: header | Returned claim ID is same as method URL. | Needs update | No: create claims by POST to /johnnysac/, update with PUT to /johnnysac/claim/XXX | | " | " | " | If claim XXX does exist, Error (what code? 403 Forbidden?) | This behaviour for existing claims allows users to submit claims with user-specified IDs without fear that they will inadvertently overwrite an existing claim with that ID. | Yes, with 403 | No: users can't choose the claim URI | | sacstore.org/johnnysac/claim/XXX | GET | | Claim RDF | | Needs update | yes | | sacstore.org/johnnysac/claim/XXX | DELETE | | | Deletes a claim | | Needs update | | alternatives... | | sacstore.org/johnnysac/ | PUT | - | Error 405 | Not allowed. NB: The response MUST include an Allow header containing a list of valid methods for the requested resource. (HTTP standards) | Needs allow header | |
The way the qsac interface turned out, the claim URIs can be opaque -- ie, the .../claim/XXX structure can be undocumented, or at least not committed to. This means users only generate the SAC URI, and only GET, PUT or DELETE claim URIs which they received in the Location header of a POST to the SAC URI (hmm: do we need to be able to get a list of all claims in a SAC, somehow?) Java/Python interfaceThis will probably be specified as a Java interface first, though we expect to describe a python version, for example, as well. It's expected to be a fairly lightweight overlay on the HTTP interface above, acting both as a convenience layer and as a layer which adds some higher level concepts, and perhaps some consistency constraints. More to come...
|
Sign in to add a comment
