Formats
Cloud CMS supports request and response payloads in a multitude of formats, including:
Text Formats
Binary Formats
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