Media Service RESTful API

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:

Unknown macro: {multi-excerpt}

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)
'Original' (the original, full-sized image, in its native format; e.g. JPEG, PNG, TIFF, etc.)

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 -with optional URI to media bits (document/file).

Notes: Returns the csid of a newly created media record as part of the URL in the 'location' header of the response. If the POST payload includes a 'blobUri' query parameter that is set to a valid and accessible URI, then the Media service will attempt to create a corresponding blob record using that URI and will relate it to the newly created media record. See the following link for more details: Blob Service RESTful API

Supported URL protocols

If the 'blobUri' refers to an HTTP resource, the service assumes the resource is not protected -i.e., does not require authentication credentials.

If the 'blobUri' refers to a FILE resource, the file must exists on (or be reachable from) the same machine upon which the Blob service is running. It also means that the appropriate file-system permissions exist on the resource such that the service can access and read it.

2. Create a new media record AND a blob record

Notes: This creates both a media record and a blob record and also relates the two.

3. Create a new blob record and relate to an existing media record - Option #1

Notes: Returns the csid of the blob record. In addition, this operation has the side-effect of relating the existing media record (with csid) to the newly created blob record.

4. Create a new blob record and relate to an existing media record - Option #2 - URI Source.

Notes: Returns the csid of the blob record. Use the query parameter 'blobUri' to set a URI path to the blob file/document. This operation also has the side-effect of relating the media record with csid to the newly created blob record.

Supported URL protocols

If the 'blobUri' refers to an HTTP resource, the service assumes the resource is not protected -i.e., does not require authentication credentials.

If the 'blobUri' refers to a FILE resource, the file must exists on (or be reachable from) the same machine upon which the Blob service is running. It also means that the appropriate file-system permissions exist on the resource such that the service can access and read it.

Media Service GET requests.

1. Get an existing media record.

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

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

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

4. Get the blob content's raw 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.

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

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

Notes: Returns the derivative's content data.

8. Get a specific derivative content's raw 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.

Notes: Returns the csid of the schema record.

2. Update an existing schema record AND blob record - Option #1

Notes: The payload must include a 'blobUri' parameter that is set to a valid and accessible URI.

As of v1.5, the 'blobUri' query parameter can only be an absolute file path to a document/file that the Blob service can access. This usually means that it must be a file/document that exists on the same machine upon which the Blob service is running. It also means that the appropriate file system permission must exist on the file/document.

3. Update an existing media record and blob record - Option #2

Notes: This update will create a new blob record from the embedded file/document include in the POST request. It will relate the new blob record to the media record that has an ID equal to csid. Any existing relationship that the media record has 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

Service Description Repository