API Reference - Data Formats
This section details the data formats used for requests and responses when interacting with our APIs. Understanding these formats is crucial for successful integration.
Common Data Formats
We primarily support the following data formats. Always check specific endpoint documentation for required or supported formats.
JSON (JavaScript Object Notation)
Description: Lightweight, human-readable text format for data interchange. Widely used for web APIs.
Content-Type: application/json
Use Cases: Most common for request bodies and responses.
Example:
{
"id": 123,
"name": "Example Item",
"active": true,
"tags": ["api", "data"]
}XML (Extensible Markup Language)
Description: A markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable.
Content-Type: application/xml or text/xml
Use Cases: Legacy systems, specific integrations, or where strict schema adherence is required.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<item>
<id>123</id>
<name>Example Item</name>
<active>true</active>
<tags>
<tag>api</tag>
<tag>data</tag>
</tags>
</item>Form URL Encoded
Description: Used to encode data submitted by an HTML form. Key-value pairs are concatenated with '&' and keys/values are URL-encoded.
Content-Type: application/x-www-form-urlencoded
Use Cases: Simple form submissions, often for POST requests where data is not complex.
Example:
id=123&name=Example%20Item&active=true&tags[]=api&tags[]=dataPlain Text
Description: Unstructured text data.
Content-Type: text/plain
Use Cases: Simple string payloads, logs, or configuration values.
Example:
This is a simple text message.Request Data Formatting
Sending Data
When sending data to our APIs, you will typically use one of the supported formats in the request body. The Content-Type header must accurately reflect the format of the data you are sending.
- For JSON payloads, set
Content-Type: application/json. - For XML payloads, set
Content-Type: application/xml. - For form submissions, set
Content-Type: application/x-www-form-urlencoded.
Best Practice: Unless specifically required otherwise, we recommend using JSON for its simplicity and widespread adoption.
Response Data Formatting
Receiving Data
Responses from our APIs will generally adhere to the requested format, or default to JSON if no preference is specified.
The Accept header in your request can be used to indicate your preferred response format. For example, to request JSON, you can include:
Accept: application/jsonIf no Accept header is provided, the API will typically default to returning JSON.
Note: Some endpoints may have specific limitations on the formats they support for responses.
Data Types and Conventions
Within these formats, certain data types and conventions are followed:
- Strings: Enclosed in double quotes (
"like this"). - Numbers: Integers or floating-point values (
123,123.45). - Booleans:
trueorfalse(lowercase, no quotes). - Arrays: Ordered lists of values enclosed in square brackets (
[value1, value2]). - Objects: Unordered key-value pairs enclosed in curly braces (
{"key": "value"}). Keys are always strings. - Null: Represented by the keyword
null(lowercase, no quotes).
Ensure your data adheres to these conventions for seamless API interaction.