Cloud CMS supports the storage of binary files into one of three possible storage locations:

  • MongoDB GridFS
  • Amazon S3
  • Local file system

Binary files are stored using directory structures (key prefixes) that allow for fast object retrieval from any of these systems. These storage paths are optimized for retrieval and write speed and are subject to implementation changes.

The actual API retrieval of these files, on the other hand, utilizes a simple filename convention. You simply retrieve the binary resource without having to worry about how the back end storage is managed.

MongoDB Grid FS is the default storage mechanism and is left enabled for Docker installations.

The public cloud uses Amazon S3 which is what we recommend for all production installs that you intend to scale elastically across multiple API server instances

The local file system implementation can be used for single-server development boxes.

Every binary retains information about the content type, length and stream. The filename is also optionally stored with the binary.

Data Store Binaries

Every data store in Cloud CMS supports straight binary storage. If you have CREATE_SUBOBJECTS permissions against the data store, you can store binaries within it.

For example, you might upload a file to a Repository like this:

POST /repositories/{repositoryId}/files/{filename}

The HTTP POST's content type header and stream will be read from and written into the binary object identified by filename.

You can then retrieve the file like this:

GET /repositories/{repositoryId}/files/{filename}

Or delete it like this:

DELETE /repositories/{repositoryId}/files/{filename}


In addition to raw data store storage, Cloud CMS also supports per-object storage called "attachments". Attachments are similar in concept to email attachments in that they're additional binary payloads attached to a JSON object. They aren't part of the JSON data itself but rather ancillary binary parts that ride alongside it.

The Attachments API is delivered as a suffix to the object itself. The upload and download mechanisms are the same and the HTTP headers are all worked with in the same way.

For example, to upload an attachment to a content node, you'd do this:

POST /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/attachments/{attachmentId}

Where the attachment is identified by attachmentId. The only way to then retrieve this attachment is to scope the request against the node, as in:

GET /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/attachments/{attachmentId}

Under the hood, attachments are simply binary files that are stored against the very same GridFS, S3 or file storage systems. In the case of attachments, the filenames are dynamically generated on the fly so as to associate the underlying file with the object it is being attached to. This generation of filenames helps to ensure there are no collisions and that storage is optimal.

For more information on attachments, please read about Attachments.