CollectionSpace ServiceREST-based APIs

June 2009 Face-to-faceAron Roberts

U.C. Berkeley IST/Data Services

CollectionSpace 2

Agenda

• Overview: REST in 3 slides

• Summary: REST-based APIsproposed for the Services Layer

• Request: Feedback (later-on)

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

CollectionSpace

CollectionSpace 4

REST … in 2 slides …Every resource is URL-addressable:

/collectionobjects/collectionobjects/{id} /loans

You can get creative!

/collectionobjects/moviescripts/loans/overdue

CollectionSpace 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

CollectionSpace 6

RESTful APIs (proposed)

Create  POST a new item to a “bucket”POST /collectionobjects

Read  GET an item by its IDGET /collectionobjects/{id}

Read (multiple)  GET the items in a “bucket”GET /collectionobjects

CollectionSpace 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

CollectionSpace 8

RESTful APIs (proposed)

Update  PUT a fully updated item to an IDPUT /collectionobjects/{id}(Partial updates not REST-defined, however.)

Delete  DELETE an item by its IDDELETE /collectionobjects/{id}

Resource discovery  GET info about resourceGET /collectionobjects/schemaGET /collectionobjects/description

CollectionSpace 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

CollectionSpace 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 …

CollectionSpace 11

Status CodesHTTP 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.

CollectionSpace 12

Error ResponsesResponse in body when a 4xx or 5xx status is returned:

<error> <code>{Mandatory code}</code> <message>{Optional message}</message> <resource-id>{Resource ID, if available}

</resource-id> <request-uri>{URI of request}</request-uri></error>

CollectionSpace 13

More infoREST-based APIshttp://wiki.collectionspace.org/x/yYD8 Common System Specific Elementshttp://wiki.collectionspace.org/x/iID8(payloads, error messages, and more!)

CollectionSpace 14

Feedback• Eagerly invited. (Probably later on!)

• We seek consistency, and to share ideas, with other CollectionSpace teams re REST-based APIs.