1. CollectionSpace Service REST-based APIs June 2009 Face-to-face Aron Roberts U.C. Berkeley IST/Data Services

2. Agenda Overview: REST in 3 slides Summary: REST-based APIs proposed for the Services Layer Request: Feedback (later-on) 2CollectionSpace

3. REST … in 1 slide … “… resources are just consistent mappings from an identifier [such as a URL path] to some set of views on server-side state. “If one view doesn’t suit your needs, then feel free to create a different resource that provides a better view … “These views need not have anything to do with how the information is stored on the server … [They just need] to be understandable (and actionable) by the recipient.” – Roy T. Fielding 3CollectionSpace

4. REST … in 2 slides … Every resource is URL-addressable: /collectionobjects /collectionobjects/{id} /loans You can get creative! /collectionobjects/moviescripts /loans/overdue 4CollectionSpace

5. REST … in 3 slides … To change system state, simply change a resource. Within the /collectionobjects “bucket”, you can: Create an item Update an item with new data Delete an item 5CollectionSpace

6. RESTful APIs (proposed) Create POST a new item to a “bucket” POST /collectionobjects Read GET an item by its ID GET /collectionobjects/{id} Read (multiple) GET the items in a “bucket” GET /collectionobjects 6CollectionSpace

7. RESTful APIs (proposed) Read (multiple) GET the items in a “bucket” GET /collectionobjects Need to define details of: IDs – CSIDs, museum numbers Filtering – child resources, query parameters Paging Formats returned – URLs, full records 7CollectionSpace

8. RESTful APIs (proposed) Update PUT a fully updated item to an ID PUT /collectionobjects/{id} (Partial updates not REST-defined, however.) Delete DELETE an item by its ID DELETE /collectionobjects/{id} Resource discovery GET info about resource GET /collectionobjects/schema GET /collectionobjects/description 8CollectionSpace

9. RESTful APIs (proposed) Search Not REST-defined. Often: GET /collectionobjects?q=term Need to define: “Simple” search Fully-specified search – Resource-oriented – Query parameters – Forms submission 9CollectionSpace

10. RESTful APIs (proposed) Search (cont’d) If we model searches as resources: Create POST a new search POST /searches Read GET search results GET /searches/{id}/results Searches might thus be saved, shared … 10CollectionSpace

11. Status Codes HTTP status codes returned in the response header: 200 OK The resource was read, updated, or deleted. 201 Created The resource was created. 400 Bad Request The data sent in the request was bad. 403 Not Authorized The Principal named in the request was not authorized to perform this action. 404 Not Found The resource does not exist. 409 Conflict A duplicate resource could not be created. 500 Internal Server Error A service error occurred. 11CollectionSpace

12. Error Responses Response in body when a 4xx or 5xx status is returned: {Mandatory code} {Optional message} {Resource ID, if available} {URI of request} 12CollectionSpace

13. More info REST-based APIs http://wiki.collectionspace.org/x/yYD8 Common System Specific Elements http://wiki.collectionspace.org/x/iID8 (payloads, error messages, and more!) 13CollectionSpace

14. Feedback Eagerly invited. (Probably later on!) We seek consistency, and to share ideas, with other CollectionSpace teams re REST-based APIs. 14CollectionSpace