wiki:NDG3/Vocab/RestfulAPI

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

interim addition of material on Restful API

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
    • vocab.ndg.nerc.ac.uk/lists/listID/versionNo
      • GET is the only operation supported on a versioned list.
        • Acceptable responses:
          • 200 OK
    • vocab.ndg.nerc.ac.uk/lists/listID defaults to current version.
      • GET returns a complete list (format tbd)
      • PUT provides a set of updates for a list (e.g. a set of five operations to members of one 20,000 member list).
      • POST provides a completely new version of the list. (Not to be supported in first version of the software)
      • DELETE not supported.
    • 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.

0 Items

  • vocab.ndg.nerc.ac.uk/items/listID/memberID/versionNo
  • vocab.ndg.nerc.ac.uk/items/listID/memberID defaults to current version

0 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.
    • No other operation permitted.

will carry out a query (tbd) against the vocabulary server. }}}