Version 2 (modified by lawrence, 13 years ago) (diff)

another interim

API for RESTful access to the NDG Vocabulary Server

This is a draft specification. Subject to change. And the thinking on this page is not yet complete, so ignore it for now, unless you are following the mailing list!

 Basic REST URI concept:

Use HTTP methods:

HTTP Method Concept Description
GET Retrieve Retrieve a representation of a resource
POST Create Create a new resource
PUT Update Update a resource
DELETE Delete Remove a resource.(This last needs careful consideration in our application)

On defined formats. (We need to define them).

Expect  status codes plus informative messages in headers, as well as response payloads where appropriate.

(Note that while we can see some advantages to following some aspects of the Atom protocol, the main concept of a list is not identical to that of a collection, so we deviate a little).

The basic uri space looks like

  1. Lists
      • GET is the only operation supported on a versioned list.
        • Acceptable responses:
          • 200 OK
          • 404 Not Found (not a valid list).
          • 406 Not Acceptable (not a valid version)
    • defaults to current version.
      • GET returns a complete list (format tbd)
        • Response codes as above sans 406.
      • PUT provides a set of updates for a list (e.g. a set of five operations to members of one 20,000 member list).
        • Acceptable responses:
          • 202 Accepted for processing.
          • 404 Not Found (not a valid list)
          • 406 Not Acceptable (syntax of updates is broken)
      • POST provides a completely new version of the list. (Not to be supported in first version of the software)
        • At this version: respond with a 405 Method not allowed.
      • DELETE not supported.
        • At this version:
    • Note primary assumption. We cannot create a completely new list using these methods. The list denoted by listID has to exist a priori! (We might imagine at some future time support for a new path something like: ... which supports POST, but that is not anticipated any time soon). In the mean time, list creation to be carried out by direct negotiation with BODC.
    • returns a complete set of pending updates on listID.
      • GET returns the updates
        • Acceptable Responses:
          • 200 OK
          • 204 No content for that list
          • 404 Not a valid list
      • All other options not allowed, return 405 Method not allowed for a POST, PUT, UPDATE, DELETE.

0 Items

  • defaults to current version

0 Querys

    • GET should return the URIs of matches as an atom collection, and provide paging should the result set be large.
    • No other operation permitted.

Hanging Issues =

  • Where to portion the issue associated with a client retrieving a set of updates, and sending back a new set. What if they conflict?