Blob Service RESTful API

Owned by Jesse Martinez
Last updated: Apr 30, 2015 by Aron Roberts (Unlicensed)Version comment
4 min read

Unknown macro: {multi-excerpt} The Blob Service offers a RESTful API to perform CRUD (create, read, update, and delete) operations on file/document related information. Included in this information is the type and encoding of a file, and a reference to the location of the actual file/document bits.

When possible, these operations follow the Common model for CollectionSpace REST services.

Assumptions and Definitions of Terms

A "blob record" refers to an instance of the Blob Info Schema: it contains information about a specific document/file's type, encoding, etc. and a reference to the actual file/document bits. For example, if the actual file is a JPEG image then the blob record would have its file type (MIME type) field set to image/jpeg.

Blob Derivatives

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

Eventually derivative terms and the properties of these terms will be part of the CollectionSpace configuration mechanism. However this is currently out of scope for the 1.x version of the service. Derivative terms and their corresponding properties will be specific to the file/document type. For example, for an image file, a term set definition might look something like:
Unknown macro: {multi-excerpt-include}
Table of Contents

Related Links:

Blob Info Schema

Blob Service CREATE requests

1. Create a new blob record and persist a related document/file- Option #1

This creates a blob record as well as stores and relates a copy of the posted file. The information in the blob record (see Blob Info Schema) is automatically populated by the Blob service based upon the file/document that is posted with the request.

Notes: Returns the csid of the blob record. The csid is part of the fully qualified URL that is returned in the location header of the HTTP response.

The blob service expects a POST similar to the one web browsers use to upload files. See the following HTML snippet for how you can use a web browser to post a new blob.


2. Create new blob record - POST request contains no embedded document/file payload - Option #2

Notes: Using the 'blobUri' query parameter, you can include a URI to a FILE resource or an HTTP resource that you want the service to use when creating the blob record. If the URI is set and valid, then the Blob service will try to use the URI to create a blob record as well as store and relate a copy of the document/file. The information in the blob record (see Blob Info Schema) is automatically populated by the Blob service and derived from the resource pointed to by the URI.

If the blobUri query parameter is empty or missing then the Blob service will instead expect a blob record payload -see Blob Info Schema.

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.
Blob Service GET requests.

3. Get an existing blob record.

Notes: Returns the blob record corresponding to the csid -see Blob Info Schema. If the blob record was created with a document/file then a URL to the blob's content (the document/file) is included in the resulting payload.

4. Get an existing blob's data content.

Notes: If the blob record was created with a document/file then this returns the blob data content (a file/document) corresponding to the blob record's csid

5. Get the full set of raw metadata about an existing blob record's content.

Notes: Returns the full set of raw metadata that exists for the content of the blob record with csid. This metatdata will essentially be a property bag specific to the media-type/MIME-type of the content.

6. Get a list of derivatives for an existing blob record.

Notes: Returns a list of blob derivatives corresponding to the blob record's csid. This will include a URL to each derivative.

7. Get a specific derivative record of an existing blob record.

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.

8. Get a specific blob derivative's content.

Notes: Returns the data content of the derivative.

9. Get the full set of raw metadata about an existing blob derivative.

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

Blob Service UPDATE requests:

1. Update an existing blob record.

Notes: Returns the csid of the blob record.

This PUT request to /blobs/{csid} is not currently implemented. Please see CSPACE-6633 for updates.

 

2. Update an existing blob record:

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