So, what is a sensible API for an editor? My thinking is that an editor cares about two things – updatable_lists (i.e. complete vocabularies that may be edited) and update_sets (items from a list that are to be added, deleted or modifications to existing items) (Roy, in email, 16/11/08).

My uri space would look like

1. Updatable_lists
   • vocab.ndg.nerc.ac.uk/updatable_lists
     • GET is the only supported method, which returns the URIs of the lists that may be edited by the currently authenticated user. Acceptable responses:
       • 200 OK
       • 204 No lists for authenticated user
       • 401 No user authenticated
     • POST, PUT, DELETE not supported.
       • 405 Method not allowed.
   • vocab.ndg.nerc.ac.uk/updatable_lists/listID
     • GET returns the specified list. Acceptable responses:
       • 200 OK
       • 404 Not Found (not a valid list).
       • 403 User not authorised to update the specified list
       • 401 No user authenticated
     • PUT 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.
     • POST, DELETE not supported.
       • 405 Method not allowed.
2. Update sets
   • vocab.ndg.nerc.ac.uk/update_set/listID manages updates for a specified list. Document payload may include insertions, changes and deletions as XML elements.
     • GET returns the pending updates for the specified list. Acceptable Responses:
       • 200 OK
       • 204 No updates pending for that list
       • 404 Not a valid list
       • 403 Not authorised – user cannot change specified list
       • 401 No user authenticated
     • POST provides a fresh set of pending updates. Acceptable responses:
       • 200 OK
       • 400 Specified update is already pending
       • 403 Document contains update from a different list
       • 404 Not a valid list
       • 403 Not authorised – user cannot change specified list
       • 401 No user authenticated
       • 500 Oracle exception on insert
     • PUT replaces an existing set of pending updates. Acceptable responses
       • 200 OK
       • 400 Specified update not currently pending
       • 403 Document contains update from a different list
       • 404 Not a valid list
       • 403 Not authorised – user cannot change specified list
       • 401 No user authenticated
       • 500 Oracle exception on insert
     • DELETE cancels members from an existing set of pending updates. Acceptable responses
       • 200 OK
       • 400 specified update not currently pending
       • 403 document contains updates from a different list
       • 404 Not a valid list
       • 403 Not authorised – user cannot change specified list
       • 401 No user authenticated
       • 500 Oracle error