Formats

Cloud CMS supports request and response payloads in a multitude of formats, including:

Text Formats

• JSON
• XML
• YAML
• CSV
• Java Properties

Binary Formats

• Apache Avro
• CBOR
• MessagePack
• Smile

If not otherwise specified, JSON is the assumed payload serialization format.

Once received, Cloud CMS will convert the incoming request payload (from one of the formats above) to JSON. Internally, Cloud CMS works with JSON throughout its service and DAO layer. Once the operations are complete, the response payload will be serialized out using whatever format you prefer.

In general, the request and response formats tend to match. For example, an API call might come in with the request payload in JSON format and the expectation might be for the response to be written out in JSON as well. That's quite common.

However, you're also free to mix and match. You could send requests to Cloud CMS in MessagePack and have the response come back in CSV, if you really wanted. It's up to you.

Request

To specify the request payload type, set the request Content-Type header to the MIME type that describes the incoming payload. By default, this value is assumed to be application/json. To be compliant with HTTP, you should always specify this header on every HTTP request to Cloud CMS.

As example, if you wanted to send XML data to Cloud CMS, you can set the Content-Type header to text/xml.

Response

To specify the response payload type, set the response Accept header to the MIME type that describes the response payload. If not supplied (or if a specific MIME type cannot be resolved), this value is assumed to be the same as the incoming request payload MIME type. The default is application/json.

To be compliant with HTTP, you should always specify this header on every HTTP request to Cloud CMS.

As per the HTTP specification, the Accept header can either be a specific MIME type (such as application/json) or it can be a list of MIME types in a comma-separated list. For example, you could set Accept to text/xml,text/csv which indicates that the caller expects the results to come back in one of the given formats. In this case, Cloud CMS will walk the list of MIME types and find the first one that it knows how to handle. That handler will be used to serialize the payload. In this case, it would pick text/xml.

The Accept header can also specify wildcards. For example, it could contain */* which indicates that the response can come back in any format. In this case, Cloud CMS will fall back to using the same MIME type as the request.

Alternatively, you can use the format request parameter to specify the format of the response. For example, if you wanted the response to come back as AVRO, you can set ?format=avro. If you wanted to achieve the same thing using the Accept header, you would set the Accept header to application/avro.

Finally, you can also use the file extension of the incoming URI to specify the format of the response. For example, if you wanted the response to come back as XML, you can add a .xml to the end of your URI. If you wanted to achieve the same thing using the Accept header, you would set the Accept header to text/xml.

Formats and MIME Types

The following formats and associated MIME types are supported:

JSON

This is the default format assumed by the API.

• Format: json
• MIME Types: application/json
• Extension: .json

Example

Let's create a node using JSON.

We set the Content-Type header (indicating the mimetype of the request payload) to application/json. We also set the Accept header (indicating the mimetype of the response payload) to the same value.

We're expecting to send JSON to the server and get JSON back.

curl 'https://api.cloudcms.com/repositories/9b0d7c9783aa46ba5eect/branches/4a49b6ba0d7c97123/nodes' -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"title":"Hello World"}'

The value we POST in the above call is:

{
    "title": "Hello World"
}

YAML

The YAML converter allows you to submit and retrieve data from Cloud CMS using YAML formatted documents.

• Format: yaml, yml
• MIME Types: application/yaml, application/x-yaml, text/yaml, text/x-yaml
• Extension: .yaml, .yml

Example

Let's create a node using YAML.

We set the Content-Type header (indicating the mimetype of the request payload) to application/x-yaml. We set the Accept header (indicating the mimetype of the response payload) to `/'.

We're expecting to send YAML to the server and get YAML back.

curl 'https://api.cloudcms.com/repositories/9b0d7c9783aa46ba5eect/branches/4a49b6ba0d7c97123/nodes' -H 'Accept: */*' -H 'Content-Type: application/x-yaml' --data-raw 'title: Hello World'

Note that because the Accept header is */*, the response will com eback as application/x-yaml (to match the request).

The value we POST in the above call is:

title: Hello World

XML

The XML converter allows you to submit and retrieve data from Cloud CMS using XML formatted documents.

• Format: xml
• MIME Types: text/xml
• Extension: .xml

Example

Let's create a node using XML.

We set the Content-Type header (indicating the mimetype of the request payload) to text/xml. We set the Accept header (indicating the mimetype of the response payload) to `/'.

We're expecting to send XML to the server and get XML back.

curl 'https://api.cloudcms.com/repositories/9b0d7c9783aa46ba5eect/branches/4a49b6ba0d7c97123/nodes' -H 'Accept: */*' -H 'Content-Type: application/xml' --data-raw '<ObjectNode><title>Hello World</title></ObjectNode>'

Note that because the Accept header is */*, the response will come back as text/xml (to match the request).

The value we POST in the above call is:

<ObjectNode><title>Hello World</title></ObjectNode>

CSV

The CSV converter allows you to submit and retrieve data from Cloud CMS using comma-separated value formatted text.

• Format: csv
• MIME Types: text/csv
• Extension: .csv

Example

Let's create a node using CSV.

We set the Content-Type header (indicating the mimetype of the request payload) to text/csv. We set the Accept header (indicating the mimetype of the response payload) to `/'.

We're expecting to send CSV to the server and get CSV back.

curl 'https://api.cloudcms.com/repositories/9b0d7c9783aa46ba5eect/branches/4a49b6ba0d7c97123/nodes' -H 'Accept: */*' -H 'Content-Type: text/csv' --data-raw 'title\r\nHello World'

Note that because the Accept header is */*, the response will come back as text/csv (to match the request).

The value we POST in the above call is:

Title\r\nHello WOrld

Text

The Text format is essentially the same as the JSON format. However, the response MIME type will be text/plain. This is offered to support some legacy cases where older browsers or middleware services may struggle with the application/json MIME type.

• Format: text
• MIME Types: text/plain
• Extension: .txt

Example

Let's create a node using Text.

We set the Content-Type header (indicating the mimetype of the request payload) to text/plain. We set the Accept header (indicating the mimetype of the response payload) to `/'.

We're expecting to send Text to the server and get Text back.

curl 'https://api.cloudcms.com/repositories/9b0d7c9783aa46ba5eect/branches/4a49b6ba0d7c97123/nodes' -H 'Accept: */*' -H 'Content-Type: text/plain' --data-raw '{"title":"Hello World"}'

Note that because the Accept header is */*, the response will come back as text/csv (to match the request).

The value we POST in the above call is:

{
    "title": "Hello World"
}

Java Properties

The Java Properties converter allows you to submit and retrieve data from Cloud CMS in the standard Java Properties format.

• Format: properties
• MIME Types: text/x-java-properties
• Extension: .properties, .props, .javaprops'

Example

Let's create a node using Java Properties.

We set the Content-Type header (indicating the mimetype of the request payload) to text/x-java-properties. We set the Accept header (indicating the mimetype of the response payload) to `/'.

We're expecting to send Text to the server and get Text back.

curl 'https://api.cloudcms.com/repositories/9b0d7c9783aa46ba5eect/branches/4a49b6ba0d7c97123/nodes' -H 'Accept: */*' -H 'Content-Type: text/x-java-properties' --data-raw 'title=Hello World'

Note that because the Accept header is */*, the response will come back as text/csv (to match the request).

The value we POST in the above call is:

title=Hello World

AVRO

The AVRO converter allows you to submit and retrieve data from Cloud CMS using the Apache Avro binary format. Apache Avro is binary data serialization format that results in smaller payloads and generally faster API latency.

• Format: avro
• MIME Types: application/avro
• Extension: .avro

CBOR

The CBOR converter allows you to submit and retrieve data from Cloud CMS using the RFC 8949 Concise Binary Object Representation format. CBOR is binary data serialization format that results in smaller payloads and generally faster API latency.

• Format: cbor
• MIME Types: application/cbor
• Extension: .cbor

MessagePack

The MessagePack converter allows you to submit and retrieve data from Cloud CMS using the Message Pack binary serialization format. MessagePack is binary data serialization format that results in smaller payloads and generally faster API latency.

• Format: messagepack, msgpack
• MIME Types: application/x-msgpack
• Extension: .messagepack, .msgpack

Smile

The Smile converter allows you to submit and retrieve data from Cloud CMS using the Smile binary data interchange format. Smile is binary data serialization format that results in smaller payloads and generally faster API latency.

• Format: smile
• MIME Types: application/x-jackson-smile
• Extension: .smile