About RPC Framework
The RPC framework is of the request-response category, where a client sends one message to Ditto Server and receives one response in return. The HTTP API is structured around various resources, which are endpoints you call in your code to perform specific actions, such asupdate
, and receive
corresponding responses from Ditto Server.
These resources correspond to the key elements of the Ditto document model. For more information, see Document Model.
Cloud URL Endpoint
Use the Ditto HTTP API to integrate external systems with Ditto-backed apps hosted oncloud.ditto.live
and programmatically interact with them using an
HTTP server interface.
Getting Your Canonical Root URL
For your canonical root URL, go to the Ditto portal > select your app > and then, from the Connecting via HTTP group at the bottom of the page, copy your Cloud URL Endpoint:
Swagger Endpoint
To access the HTTP API reference, use the following URL endpoint to view the OpenAPI swagger.json specification. For more information, see the official Swagger documentation > OpenAPI Specification. When accessing the swagger.json specification, make sure to replace the{canonical-root-url}
parameter with the unique app ID provided when you
created your app in the portal:
To use the HTTP API with
DQL_STRICT_MODE=false
, use /api/v5/swagger.jsonHTTP API v5 is compatible with v4. Read more about STRICT MODE and upcoming v5 behaviorhttps://{canonical-root-url}/api/[v4,v5]/swagger.json
Data Representations
Ditto uses UTF-8 to encode data. For more information, see Encoding Standard: UTF-8. Unless otherwise specified, the default representation format for individual resources is JSON, as indicated by theContent‑Type
HTTP header included in
your response:
Encoding Standard: UTF-8
Unless you have a specific requirement for a different encoding, encode your input data in UTF-8. UTF-8 is a variable-length schema for universal character encoding. For more information, see the official “UTF-8” Wikipedia article.Make sure to encode your text-based data, such as JSON, using the UTF-8 encoding.If using another format to encode, such as UTF-16, decoding errors and invalid results are likely to occur.
Encoding Formats: Binary Data
To transmit binary data, such as a media file, to Ditto Server, you must first convert it into either of the following formats:- For smaller data, use a Base64-encoded
string
. - For larger data, use an
ATTACHMENT
object. (See HTTP API - Attachments)
Binary Size | Encoding Format |
---|---|
Below 250 KB | Base64-encoded string value |
Between 250KB and 2MB | ATTACHMENT object |
2MB and above | This will be rejected as the payload is too large. Please get in contact with Ditto Support to have this limit increased for your deployment if necessary. |
string
in your request.
Failing to send binary data encoded with either Base64 or an
ATTACHMENT
, as appropriate, may result in compatibility issues leading to data corruption or loss.