This document provides suggested templates for REST-based APIs, for potential 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 /wiki/spaces/collectionspace/pages/666274329.

Some generic message payloads and envelopes that are to be used with the proposed APIs below, such as the message payloads to be returned in a response when an error occurs, are detailed in Common System Specific Elements.

...

...

This document is in process, and is currently incomplete. It has not yet been reviewed or accepted by the CollectionSpace Services Team.

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:

...

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

...

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

...

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

As RESTful Service - Ajax Patterns notes, "Error responses should ... be in human-friendly language and with examples and hyperlinks."

...

• Sent by a client in the body of a request, to perform a Create 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

...

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

...

Purpose
Creates a new resource of the specified type.

Request

POST /{resources_as_a_plural_noun}

...

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}

...

Response: Status Codes

Response: Content-Type
application/xml

Response: Location
Returns the URL for the newly-created object.

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.
Returns an empty entity body.

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

...

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

Request

GET /{resources_as_a_plural_noun}/{resource_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}

...

Response: Content-Type
application multipart/xmlmixed

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

Consists of one or more MIME message parts, each separated by a message-specific boundary line, and each part containing a separate document. Each of these parts of the message is currently of Content-Type: application/xml.

The MIME message part whose label ends in _common contains a document conforming to the "common" schema for a particular entity; that is, the schema that will be present for all tenants in a specific deployment. The "common" schema is also supported by search and other functionality which does not apply to extension schema. If there are other MIME message parts present, ending in a name other than _common, these parts will typically represent one or more extension schema, specific to the current tenant.

An example, showing two MIME message parts, each containing XML documents representing part of a CollectionObject: one containing the fields in an extension schema (collectionobject_naturalhistory), and the second containing the fields in the common schema (collectionobjects_common).

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA
date=200807181439)/JBossWeb-2.0
Content-Type: multipart/mixed;
boundary=ab8d331a-9720-45c9-a629-2c71050f1720
Content-Length: 1643
Date: Wed, 02 Dec 2009 23:18:13 GMT

--ab8d331a-9720-45c9-a629-2c71050f1720
label: collectionobjects_naturalhistory
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<ns2:collectionobjects_naturalhistory
xmlns:ns2="http://collectionspace.org/services/collectionobject/domain/naturalhistory"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://collectionspace.org/services/collectionobject/domain/naturalhistory
http://collectionspace.org/services/collectionobject/domain/collectionobjects_naturalhistory.xsd">
<nh-string>test-string</nh-string>
<nh-int>999</nh-int>
<nh-long>9999</nh-long>
</ns2:collectionobjects_naturalhistory>

--ab8d331a-9720-45c9-a629-2c71050f1720
label: collectionobjects_common
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<ns2:collectionobjects_common
xmlns:ns2="http://collectionspace.org/services/collectionobject"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://collectionspace.org/services/collectionobject
http://services.collectionspace.org/collectionobject/collectionobjects_common.xsd">
<otherNumbers>
<otherNumber>urn:org.collectionspace.id:24082390</otherNumber>
<otherNumber>urn:org.walkerart.id:123</otherNumber>
</otherNumbers>
<objectNumber>updated-objectNumber-1259718776712</objectNumber>
<briefDescription>Papier mache bird mask with horns, painted red with black
and yellow spots. Puerto Rico. ca. 8&amp;quot; high, 6&amp;quot; wide,
projects 10&amp;quot; (with horns).</briefDescription>
<objectName>updated-objectName-1259718776712</objectName>
</ns2:collectionobjects_common>

--ab8d331a-9720-45c9-a629-2c71050f1720--

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

Read (Multiple)

...

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}/{resource_identifier}/{typed_or_child_resources_as_a_plural_noun}

GET /{resources_as_a_plural_noun}/{resource_identifier}/
{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 ...}

...

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 or data element). Defaults to ascending order if the sortorder query parameter isn't present.

...

...

Response: Entity Body (on Success)
Returns a representation list of representations of the requested resourceresources, 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

...

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

Request

PUT /{resources_as_a_plural_noun}/{resource_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}

...

...

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

...

Purpose
Deletes a specific instance of this resource.

Request

DELETE /{resources_as_a_plural_noun}/{resource_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}

...

Response: Status Codes

Response: Content-Type
application/xml

...

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

Search

...

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

...

In the case of error responses, the status code MUST be supplemented by a standardized payload in the entity body of the response, containing a more detailed and complete description of the error. This payload MUST be both human and machine-readable. See Common System Specific Elements for details.

As RESTful Service - Ajax Patterns notes, "Error responses should ... be in human-friendly language." That document goes on to suggest that such responses include "examples and hyperlinks," if possible; however. However, while that is desirable, and it is not required.

References

...

Leonard Richardson and Sam Ruby, RESTful Web Services (via Safari Online if you have access)

Michael Mahemoff, et al., RESTful Service - Ajax Patterns

...

Aaron Johnson, Clearspace and Meaningful URLs

RedRata blog on REST-ful URI Design talks about different patterns, plurals and not plurals, sub-resources, etc.