Changes between Version 3 and Version 4 of NDG3/Vocab/HighLevelSpec

12/11/08 05:54:21 (11 years ago)

Interim summary of discussions on list


  • NDG3/Vocab/HighLevelSpec

    v3 v4  
    66Reason: to allow folk not at the BODC to control lists. 
    7 Status: Version 0.1. For discussion. 
     7Status: Version 0.2. In discussion. 
    9 Outputs:  
    10  * Service to allow the upload of a new version of a list 
    11    * leave it to Roy to define what this does to list members 
    12  * Service to allow the upload of a new list item (or list item definition) 
    13    * expect this to result in a new version of the item 
    14  * Web client to these services 
    15  * Deployed web client at BODC 
    16    * note express desire for other groups to be able to use their own clients to the backend service. 
     9Note that we expect a staged development, not all stages of which might occur in NDG3. 
    18 Method: 
    19  * Server: [ REST],  that is,  
    20    * we should now allow a PUT on list or list/item provided access control is respected to do an UPDATE  
    21      * successful response: 201 
    22      * Do not allow a PUT on a list or item version - return an error 405 
    23    * We should allow a POST to list/item to CREATE a new item. 
    24    * We should allow a DELETE on a list/item (what do we expect that to do)? 
    25    * (We still support a GET) 
    26  * Server, should respect local login at V0.1, that is using HTTP basic authentication. Expect to support NDG security in a later version. 
    27  * Client, initially a simple web form for items, with an upload button for lists. User logged in should be presented with a list of lists which they are allowed to manipulate. (Need to allow user login). 
    28  * Initially expect the creation of new lists to occur out of band, i.e. by negotiation with vocabulary server manager.  
     11Key architectural assumption:  
     13The vocab server will be deployed with a RESTful interface (and maybe others as well, but 
     14for NDG purposes we only care about the REST interface).  Browser clients will also 
     15be developed for navigating and populating lists. 
     17This document discusses only the issues associated with populating the lists, and 
     18has been informed by a previous version of this document and extensive  
     19[ discussion]. 
     20It is not yet complete. 
     22Currently out of scope: How to deal with mappings between items internal to lists 
     23and between lists. 
     25==== Outputs ==== 
     27 0. Service to allow list '''item''' additions, item modifications and item deprecations. 
     28   * Given we anticipate a [ RESTful] interface, we might a priori assume that this is accomplished via  
     29     * POST on a list/item to create an item in a list 
     30     * PUT on  a list/item to update an item in a list 
     31     * GET on  a list/item to return an xml document description of that item. 
     32     * DELETE on a list/item to deprecate it. 
     33   * We would expect this to be synchronous. 
     34 0. A web client that allows one to interact with a list and make modifications to items via the service interface (thus providing a complete test case for the service interface as well as a functional tool for list modification). 
     35   * Initially expect this to use local http authentication, and move to NDG security in a subsequent release (beyond NDG3). 
     36     * Note that the creation of user accounts should be out of band. 
     37   * After login expect to offer a user a selection of lists for which they have permission to modify. 
     38 0. Service to allow ''list'' modifications. In practice we expect this to consist of a set of item modifications, which would be carried out as above. 
     39   * Initially provide a synchronous response but consider that for post NDG3 we might allow asynchronous responses for large sets. 
     40   * We would expect the RESTful interface to look something like: 
     41     * POST would return an error (list creation should be out of band, ie via negotiation with the content provider - BODC). 
     42     * PUT would update the list 
     43     * GET would download a copy 
     44     * DELETE would return an error (lists cannot be deleted). 
     45 0. The backend service would be expected to carry out certain automatic quality control activities. 
     46    * Clearly in the case of item modifications one can only check the internal validity of the item 
     47    * For set modifications there might be consistency checks between set members 
     48    * (and obviously double check the permissions) 
     49 0. The backend service would operate by collecting up modifications to a list during the day into a "working copy of the list" (which we need to be able to separately address), and then update the official version of the list at a specific time (and increment the list version).  
     50   * It should be possible for a list governor to contact BODC out of band to get the working copy manually propagated to the official version in extremis. 
     52(Note that all methods should return appropriate http access codes) 
     54==== Use Cases ==== 
     56 * CF maintainer. Complete collection of list changes. (Currently provided as one xml document?, so how would that work). 
     57 * Metafor designer: 
     58   * needs to be able to get controlled vocab lists created by negotiation with BODC 
     59   * needs to be able to add items to controlled vocab lists as they arise. 
     60 * NERC DDC staff member 
     61  * as for Metafor designer