This document provides suggested templates for REST-based APIs, for adoption by many of the services in CollectionSpace's services layer. This implements part of the work described in the "REST Service Contracts" section of Web Services - Paradigms and Contracts

REST-based APIs, and their associated client-visible resource models, are suggested below for the three major types of CollectionSpace services: entity services, relation (association) services, and task services:

REST-based APIs for Entity Services

• Service Discovery
  • Description
  • Schema
• CRUD Operations (Create, Read, Update, Delete)
  • Create
  • Read
  • Read (Multiple)
  • Update
  • Delete
• Search rough, in-process notes

REST-based APIs for Relation (Association) Services

REST-based APIs for Task Services

REST-based APIs for Entity Services

Service Discovery

Description

Purpose
Retrieves a human-readable description of the service. This also verifies that the service exists, without interacting with the resources that it provides.

Request

GET /{resources_as_a_plural_noun}/description

Request: Entity Body
The body of this request SHOULD be empty. If it is non-empty, the body will be ignored.

Response: Status Codes

Response: Content-Type

• text/plain (for plain text)
• application/xml (for generic XML content)
  See Questions or Issues, below.

Response: Entity Body (on Success)
Returns a human-readable description of the service: in plain text, in an XML format, or both, TBA. See Questions or Issues, below.

Questions or Issues

• We need to decide if this description is made available in plain text, in a particular XML format, or both. If both, the default format can be retrieved using the pattern above, and specific formats can be retrieved by adding filename extensions; e.g.:
  • /{resources_as_a_plural_noun}/description.txt (for a plain text description)
  • /{resources_as_a_plural_noun}/description.xml (for an XML-based description)

Schema

Purpose
Retrieves the schema for the XML-based message payload that is exchanged in several of this service's operations.

Instance documents conforming to this schema may be exchanged in a variety of contexts. For instance, they may be:

• Sent by a client in the body of a request, to perform a Creation operation.
• Sent by a client in the body of a request, to perform an Update operation.
• Returned by the service in a response, when a specific object (entity) is requested.
• Returned by the service in a response, when a list of objects (entities) is requested, in a format that returns full object records, (rather than just hyperlinks, or just hyperlinks accompanied by abbreviated object records).

Request

GET /{resources_as_a_plural_noun}/schema

There will be only one schema returned per resource. If there may be typed resources, or child resources, available anywhere within the URL path, schemas for these resources can be retrieved via variations on this generic pattern, as in this example:

GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/schema

Request: Entity Body
The body of this request SHOULD be empty. If it is non-empty, the body will be ignored.

Response: Status Codes

Response: Content-Type
application/xml (for schemas expressed in XML-based schema languages)

Response: Entity Body (on Success)
Returns the schema for the XML-based message payload that is exchanged in several of this service's operations.

By default, the schema will be declared in the W3C XML Schema language.

Questions or Issues

• If there may be a requirement to return schemas in additional schema languages, such as RELAX NG, the default format can be retrieved using the pattern above, and specific formats can be retrieved by adding filename extensions; e.g.
  • /{resources_as_a_plural_noun}/schema.xsd (for a W3C XML Schema document)
  • /{resources_as_a_plural_noun}/schema.rng (for a RELAX NG schema document)

CRUD Operations (Create, Read, Update, Delete)

Create

Purpose
Creates a new resource of the specified type.

Request

POST /{resources_as_a_plural_noun}

The RESTful metaphor is that of creating a new instance of the resource within a container of, or bucket of, resources of this type.

If there may be typed resources, or child resources, available anywhere within the URL path, new resources of that type can be created via variations on this generic pattern, as in this example:

POST /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}

Request: Entity Body
If the service allows the client to supply the resource to be created:
The body of this request MUST contain a valid instance of an XML document, conforming to the schema used by the service.

If the service generates an instance of the resource algorithmically:
The body of this request SHOULD be empty. If it is non-empty, the body will be ignored.

Response: Status Codes

Response: Content-Type
application/xml

Response: Entity Body (on Success)
Returns a representation of the newly-created resource, as an XML document conforming to the schema used by the service.

Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.

Read

Purpose
Reads (aka retrieves or returns) a representation of a specific instance of this resource.

Request

GET /{resources_as_a_plural_noun}/{resource_identifier}

The {resource_identifier} is a value that uniquely identifies a particular resource. It may be an ID or some other type of identifier.

If there may be typed resources, or child resources, available anywhere within the URL path, these resources can be retrieved via variations on this generic pattern, as in this example:

GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/{resource_identifier}

Request: Entity Body
The body of this request SHOULD be empty. If it is non-empty, the body will be ignored.

Response: Status Codes

Response: Content-Type
application/xml

Response: Entity Body (on Success)
Returns a representation of the requested resource, as an XML document conforming to the schema used by the service.

Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.

Read (Multiple)

Purpose
Reads (aka retrieves or returns) a list of 0 to n instances of this resource.

Depending on the query parameters submitted, the list may include either:

• 0 to n hyperlinks, each accompanied by the minimum information required to identify, in a human-readable manner, their linked-to resources.
  • Hyperlinks are fully-qualified (i.e. not relative) URLs that may subsequently be used to retrieve any of the individual records in the list, via the Read operation, above.
  • Hyperlinks are accompanied by human-readable information, which provides a brief preview of what may be expected to be retrieved by following those links. This information is typically obtained from one or more of the information units (aka fields or data elements) in each record, and may represent an abbreviation, combination or adaptation of that information. The content of this human-readable identification is service-specific.

or

• 0 to n full records for matching resources.

The default behavior is to return hyperlinks, each accompanied by the minimum information required to identify, in a human-readable format, their linked-to resources.

Request

GET /{resources_as_a_plural_noun}

GET /{resources_as_a_plural_noun}?{optional_query_parameters ...}

If there may be typed resources, or child resources, available anywhere within the URL path, these resources can be retrieved via variations on this generic pattern, as in these examples:

GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}

GET /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}?{optional_query_parameters ...}

A highly recommended child resource, for read (multiple) operations, will return a count of the numbers of records to be returned, as in this example:

GET /{resources_as_a_plural_noun}/count

GET /{resources_as_a_plural_noun}/count?{optional_query_parameters ...}

Query parameters

Some possible examples of query parameters to modify read (multiple) requests. These in part come from Common System Specific Elements:

?orderby={information_unit}
Requests that hyperlinks or full records be returned in the natural sort order of a particular information unit (field). Defaults to ascending order if the sortorder query parameter isn't present.

sortorder={ascending|descending}
Specifies the sort order. Ignored if the orderby query parameter isn't also present.

?groupby={}
Specifies grouping of results. (Additional details TBA.)

?pagesize={nn} (or maxrecords=nn, etc.)
Return results with a maximum of nn items (hyperlinks or full records) returned per query.

?format={hyperlinks|full_records}
Requests that either hyperlinks or full records be returned. Defaults to hyperlinks.

Note that these query parameters may be combined; e.g. ?orderBy={information_unit}&pageSize={nn}

Request: Entity Body
The body of this request SHOULD be empty. If it is non-empty, the body will be ignored.

Response: Status Codes

Response: Content-Type
application/xml

Response: Entity Body (on Success)
Returns a representation of the requested resource, as an XML document conforming to the schema used by the service.

Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.

Questions or Issues

• We need to decide on XML-based representations for returning lists of entities:
  • With hyperlinks and abbreviated identification
  • With full records
• We need to fully discuss the types of query parameters required.
• We need to fully discuss how paging of the results returned (via a query parameter like pagesize or maxrecords), in responses from CollectionSpace service, will work. One way of facilitating this might be to return, in an envelope or preface in the entity body, values indicating a) the total number of records retrieved, b) the start position (index) of the first record in the current result set, and c) the numbers of records returned in that set. Note that this is not currently expected to use HTTP's Chunked Transfer Encoding mechanism. Rather, each response is expected to be a complete HTTP message, with some indication (such as the envelope or preface mentioned above) that the results returned constitute a subset of the total records available.
• We need to decide and standardize on a convention for query parameter names that combine multiple words, including case and/or punctuation (e.g. "queryparameter", "query-parameter", "queryParameter" ...)

Update

Purpose
Completely updates in place (i.e. replaces) an existing resource of the specified type.

Request

PUT /{resources_as_a_plural_noun}/{resource_identifier}

The {resource_identifier} is a value that uniquely identifies a particular resource. It may be an ID or some other type of identifier.

If there may be typed resources, or child resources, available anywhere within the URL path, resources of that type can be updated via variations on this generic pattern, as in this example:

PUT /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/{resource_identifier}

Request: Entity Body
The body of this request MUST contain a valid instance of an XML document, conforming to the schema used by the service.

Response: Status Codes

Response: Content-Type
application/xml

Response: Entity Body (on Success)
Returns a representation of the updated resource, as an XML document conforming to the schema used by the service.

Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.

Questions or Issues

• There doesn't appear to be well-defined support in the REST architecture for partial (sparse) updates of a resource, equivalent to the UPDATE table_name SET column=value statement in SQL. Some discussion:
  • Bill de hÓra, "'Just' use POST"
  • Roy T. Fielding, "It is okay to use POST"

Two of several mechanisms through which we might facilitate partial (sparse) updates, noting that these mechanisms are not currently suggested here as patterns, include:

• Providing direct access to any interesting information units (fields or data elements) via URL-addressable resources; e.g.

  /{resources_as_a_plural_noun}/

  Unknown macro: {resource_identifier}

  /{information_unit_name}

  , and then using PUT to completely update the contents of any of these individual information units.
• POSTing a partial update to the entire URL-addressable resource. The update may consist of form data in the 'application/x-www-form-urlencoded' content-type, or potentially an XML format (TBA).

Delete

Purpose
Deletes a specific instance of this resource.

Request

DELETE /{resources_as_a_plural_noun}/{resource_identifier}

The {resource_identifier} is a value that uniquely identifies a particular resource. It may be an ID or some other type of identifier.

If there may be typed resources, or child resources, available anywhere within the URL path, resources of that type can be deleted via variations on this generic pattern, as in this example:

DELETE /{resources_as_a_plural_noun}/{typed_or_child_resources_as_a_plural_noun}/{resource_identifier}

Request: Entity Body
The body of this request SHOULD be empty. If it is non-empty, the body will be ignored.

Response: Status Codes

Response: Content-Type
application/xml

Response: Entity Body (on Success)
Returns a representation of the just-deleted resource, as an XML document conforming to the schema used by the service.
If the deletion occurred in error, or an 'undo' operation is desired, the client can use this representation to once again create the resource.

Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.

Search

Approaches to Search

The two most widely used approaches to REST-based search that we have observed to date involve a) submitting a request containing query parameters, via GET and b) constructing and submitting a structure, via POST. Some variations on these approaches include:

1. Accepting GET requests with a single query parameter. (That query parameter may often be named 'q=', 'query=', or 'search='.)
2. Accepting GET requests with a multiple query parameters.
3. Using a GET request to retrieve an XHTML advanced search form, which the client can then submit to the service via a POST request. See Mark Baker's November 2006 comments on the atom-syntax list.
4. Creating a new resource within a collection of searches, populating that resource, and activating it, perhaps by POSTing it to an active searches collection, or by retrieving its "./results" child resource.

Also of interest is this proposal for a WebDAV SEARCH method.

Advanced Search

Notes: Look at Lucene search syntax, as implemented in RESTful services.

Tim Bray wrote in 2003:

... there is rough consensus among search engines on what a query should look like: quotes mark "phrase searches", you use "+" to say a word must +occur and "-" to -exclude words. You URI-restrict searches like so: tbray.org:kirkby. Down the road, you might want to support something like XPath or even XQuery, but that would work fine through a Web interface too.

So a search engine would publicize a URI that you could use HTTP GET on to run searches; arguments would be q for the query, mr for maximum results, and ie for input-encoding. So a complete search request might look like:

http://www.tbray.org/search?q=electric%20sheep&mr=20

q=%2busername:miso%20%2bhostname:miso.demo.sun.com%20%2bsubject:test

"Simple" Search

To conduct a "simple" search using default assumptions ...

Query parameters:
query=

REST-based APIs for Relation (Association) Services

Service Discovery

Description

Follows the model of the Description operation for Entity Services.

REST-based APIs for Task Services

Service Discovery

Description

Follows the model of the Description operation for Entity Services.