Media Service RESTful API

Media Service Home

The Media Service offers a RESTful API to perform CRUD (create, read, update, and delete) operations on media related information. When possible, these operations follow the Common model for CollectionSpace REST services.

Definitions and Assumptions

In the context of the Media Service, the term "media record" refers to an instance of the Media Handling Schema -it does not refer directly to the actual media data (file/document) like a JPEG image or PDF document. A "blob record" refers to an instance of Blob Info Schema -it contains information about the type of media, encoding, file size, etc and a reference to the actual media bits. For example, if the actual media is a JPEG image then the "blob record" would have its media type (MIME type) field set to "image/jpeg" and it would have an internal handle to the location of the media bits -i.e., the file/document.

Media Derivatives

Media derivatives are modeled as child blobs of the original media/document/file -this is how Nuxeo currently models them. From the context of the original media, derivatives can be referenced with terms from a controlled set of terms -for example, for images the terms might be 'thumbnail', 'small', 'medium', and 'large'.

Derivative terms and the properties of these terms will eventually be part of the CollectionSpace configuration mechanism -as of v1.5, this configuration does not yet exist. Terms and their properties will be specific to the media type. For example, for image media a term set definition might look something like:

Image Terms = {'thumbnail' = 64 x 64, 'small' = 128 x 128, 'medium' = 256 x 256 }

As of the v1.7 release, only the following image-related derivative terms exist:

'Thumbnail' (a JPEG-format derivative, 64 x 64 pixels)
'Medium' (a JPEG-format derivative, 256 x 256 pixels)
'OriginalJpeg' (a JPEG-format derivative, with the same pixel resolution as the original image)

To reduce possible call fan-out by a service consumer, URL's to the media derivatives will be part of the GET payload request for media records -assuming, of course, that the media record has been related to a blob record and that it has derivatives.

Media Service CREATE requests

1. Create a new media record

POST to "/media" with MIME=application/xml

Returns the CSID of the newly created media record as part of the URL in the Location: header of the response.

2. Create a new media record AND create an associated blob record

POST to "/media?blobUri=" with MIME=application/xml

Returns the CSID of the newly created media record as part of the URL in the Location: header of the response. The Media service will also attempt to create a corresponding blob record by retrieving the media at the URL provided in the blobUri= query parameter, and if successful, will associate that blob record to the newly created media record. (See also the Blob Service RESTful API for more details on blob records and alternate methods for creating such records.)

Supported URL protocols for the blobUri= query parameter

If the 'blobUri' refers to an HTTP resource (http://), the service assumes the resource is not protected; i.e. does not require authentication credentials to be accessed.

If the 'blobUri' refers to a file resource (file://), the file must exists on (or be reachable from) the same machine upon which the Blob service is running. The file must also have appropriate filesystem permissions to allow the Media service to access and read it.

Media Service GET requests.

1. Get an existing media record.

GET to "/media/{csid}"

Returns the media record corresponding to passed in csid. Also, if there is a related blob record, it returns a set of URL's -pointing to the original media data and any derivatives.

2. Get an existing blob record from the Media service.

GET to "/media/{csid}/blob"

Returns the blob record corresponding to the media record's csid. Also, it returns a set of URL's -pointing to the original media data and any existing derivatives.

3. Get an existing blob's data content (actual bits) from the Media service.

GET to "/media/{csid}/blob/content"

Returns the blob data content corresponding to the media record's csid

4. Get the blob content's raw metadata.

GET to "/media/{csid}/blob/content/metadata"

Notes: Returns the full set of raw metadata that exists for the blob's content -for example, EXIF metadata for images.

5. Get an existing blob's derivatives.

GET to "/media/{csid}/blob/derivatives"

Returns a list of a blob derivatives corresponding to the blob record's csid -each existing derivative will be uniquely identified with a derivative term -see the description of derivative terms at the top of this page. The result payload will also include a URL to each derivative's data bits.

6. Get a specific derivative from an existing blob's derivatives.

GET to "/media/{csid}/blob/derivatives/{derivative_term}"

Returns what is essentially a "blob record" for the specified blob derivative. Initially, the derivative term will be one of a small set of controlled terms -i.e., 'thumbnail', 'small', 'medium', etc. Derivative terms will be defined in a CollectionSpace configuration file.

7. Get a specific derivative's content from an existing blob's derivatives.

GET to "/media/{csid}/blob/derivatives/{derivative_term}/content"

Returns the derivative's content data.

8. Get a specific derivative content's raw metadata.

GET to "/media/{csid}/blob/derivatives/{derivative_term}/content/metadata"

Notes: Returns the full set of raw metadata that exists for the derivative's content.

Media Service UPDATE requests:

1. Update an existing media record.

PUT to "/media/{csid}" with MIME=application/xml

This operation updates an existing media record (with the provided CSID) and returns the updated Media record.

2. Update an existing media record AND create an associated blob record - Option #1

PUT to "/media/{csid}?blobUri=" with MIME=application/xml

This operation updates an existing media record (with the provided CSID) and returns the updated Media record. The Media service will also attempt to create a corresponding blob record by retrieving the media at the URL provided in the blobUri= query parameter, and if successful, will associate that blob record to the newly created media record. Any existing association that the media record had with another blob will be lost.

Supported URL protocols for the blobUri= query parameter

If the 'blobUri' refers to an HTTP resource (http://), the service assumes the resource is not protected; i.e. does not require authentication credentials to be accessed.

If the 'blobUri' refers to a file resource (file://), the file must exists on (or be reachable from) the same machine upon which the Blob service is running. The file must also have appropriate filesystem permissions to allow the Media service to access and read it.

3. Update an existing media record AND create an associated blob record - Option #2

PUT to "/media/{csid}/blob" with MIME=multipart/form-data

This operation updates an existing media record (with the provided CSID) and returns the updated Media record. The Media service will also attempt to create a corresponding blob record from media data (typically a BASE64-encoded image, document, etc.) that was uploaded in a single part of the body of the PUT request, and if successful, will associate that blob record to the newly created media record. Any existing association that the media record had with another blob will be lost.

List Media instances

Lists existing Media records, with summary information for each.

Summary Fields returned: title, source, filename, identificationNumber

Example:

GET /cspace-services/media HTTP/1.1

CollectionSpace Unreleased Documentation