wiki:NDG3/Vocab/RestfulAPI

Version 7 (modified by lawrence, 11 years ago) (diff)

navigation

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, in particular the payload that one posts to a resource may differ from that which one puts to a resource, the latter being an update, the former being a creation of a new version completely).

The basic uri space looks like

  1. Lists
    • vocab.ndg.nerc.ac.uk/lists/listID/versionNo
      • 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)
    • vocab.ndg.nerc.ac.uk/lists/listID 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.
        • 405 Method not allowed.
    • 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: vocab.ndg.nerc.ac.uk/create/listID ... 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.
    • vocab.ndg.nerc.ac.uk/updates/listID 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.
  2. Items
    • vocab.ndg.nerc.ac.uk/items/listID/memberID/versionNo
      • GET Acceptable responses:
        • 200 OK
        • 404 Not Found (not a valid member or list).
        • 406 Not Acceptable (not a valid version)
      • PUT, POST, UPDATE, DELETE, 405 Not allowed.
    • vocab.ndg.nerc.ac.uk/items/listID/memberID defaults to current version
      • GET (download memberID) Acceptable responses:
        • 200 OK
        • 404 Not Found (not a valid member or list).
      • PUT (modify the entry at memberID) Acceptable responses:
        • 202 Accepted for processing
        • 404 Not Found (not a valid list or member)
        • 406 Not Acceptable (syntax of update is broken)
      • POST creates a new member of the list. Acceptable responses:
        • 202 Accepted for processing
        • 404 Not found (not a valid list)
        • 406 Not Acceptable (syntax of update broken)
      • DELETE deprecate the memberID.
        • 202 Accepted for processing
        • 404 Not found (not a valid list or member)
  3. Querys
    • vocab.ndg.nerc.ac.uk/query?find=string
      • GET should return the URIs of matches as an atom collection, and provide paging should the result set be large.

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?
  • Everything to do with mappings.
  • Ought to consider whether the PUT/POST thing for lists might cause problems in the future.

Vocab: HighLevelSpec, APIRestIssues

NDG3: Capability, Discovery, Vocab, Software, MOLES, Security, Community, Roadmap