Skip to end of metadata
Go to start of metadata

As part of the UI rewrite, three new acronyms features have landed in the CollectionSpace services layer. These will be available in the next release of CollectionSpace (tentatively numbered 4.5). You can try them today by building and deploying the master branch to your own server, or by hitting our nightly build server at http://nightly.collectionspace.org:8180/cspace-services.

 

JSON Output

The REST API now returns data in JSON format when requested, and accepts data in JSON format when it is provided. This is a necessary step towards eliminating the application layer.

The services layer treats XML as its first-class serialization format; it contains code that explicitly generates XML and expects to receive XML. For this reason, the JSON provided as output and expected as input is not a direct serialization of CollectionSpace resources. Instead, JSON is produced by converting XML output as it exits the services layer, and JSON is converted back into XML as it enters the services layer. This results in a couple of oddities, like using @ to prefix fields that are translated from XML attributes, and using @xmlns: to prefix fields that correspond to XML namespace declarations.

To request data in JSON format, send the HTTP Accept header, with value application/json:

To send data in JSON format, send the HTTP Content-Type header, with value application/json:


OAuth 2 Tokens

The REST API now grants and accepts authorization tokens. This is another step towards eliminating the application layer. 

Tokens are granted following the OAuth 2 specification. Currently only the resource owner password credentials grant and refresh token grant are supported. Only one client identifier is currently allowed: cspace-ui. In the terminology of the specification, the cspace-ui client represents a public client and a user-agent-based application. Since this client is public (and therefore incapable of keeping a secret), the client secret (sent as the basic auth password in the following examples) is empty.

Tokens my be obtained by sending a POST request to the /oauth/token endpoint:

This returns an access token and a refresh token.

The access token may be used to authorize requests against CollectionSpace resources. This is done by sending the HTTP Authorization header:

The refresh token may be used to obtain a new access token – typically, after the current access token has expired. This is done by sending a POST to the /oauth/token endpoint:

Notes:

  1. Access tokens are set to expire in one hour, and refresh tokens in 12 hours. Once the refresh token has expired, the user must re-authenticate with their username and password.
  2. The tokens are JWT, but this may change in the future. For now they should be considered opaque strings.
  3. The above examples are contrived to demonstrate how the API is used. For one-off curl requests, it's easier to use basic auth, which is still supported. Token auth is preferred when you're using a client that handles the token management for you.
  4. Tokens are signed with a random key generated when the services layer starts. Restarting the CollectionSpace server changes the signing key, invalidating all outstanding tokens. This means that all users must re-authenticate with their username and password. Restarting CollectionSpace is in fact the only way to revoke an outstanding token. There is no way to revoke an individual token; they will all be invalidated.

Future enhancements will include configurability – for example, of allowed client identifiers and associated secrets, token expiration times, and token signing keys – and support for additional OAuth 2 grant types. Additional design work around revoking individual tokens is also required.

 

CORS

The REST API may now be configured to accept cross-origin requests. This allows flexibility in deploying JavaScript applications that utilize CollectionSpace services. An application served from a museum's own domain (e.g. http://hearstmuseum.berkeley.edu) may now access CollectionSpace at a hosting provider's domain (e.g. http://cspace.berkeley.edu). For example, a hosting provider might choose to host only the CollectionSpace services layer, while a museum hosts the UI on their own servers.

Cross-origin requests are not allowed by default. Domains may be whitelisted for CORS on a single CollectionSpace server by adding a security.properties file to tomcat's lib directory. The cors.allowed.origins property accepts a comma separated list of domains:

security.properties

Alternatively, the default value of cors.allowed.origins may be modified in the source tree by editing applicationContext-security.xml.