---
title: "Formats"
description: "Explore Cloud CMS's versatile data serialization, supporting formats like JSON, XML, YAML, CSV, and more, tailored to your API needs. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/developers/api/formats"
---

# Formats

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

**Text Formats**

- [JSON](#json "JSON")
- [XML](#xml "XML")
- [YAML](#yaml "YAML")
- [CSV](#csv "CSV")
- [Java Properties](#java-properties "Java Properties")

**Binary Formats**

- [Apache Avro](#avro "Apache Avro")
- [CBOR](#cbor "CBOR")
- [MessagePack](#messagepack "MessagePack")
- [Smile](#smile "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 an 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 come back 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 a 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 a 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 a 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 a binary data serialization format that results in smaller payloads and generally faster API latency.

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