Skip to main content

API Reference

OpenAPI

The Open API swagger.json spec can be found at the following URL:

  • https://{app_id}.cloud.ditto.live/api/v4/swagger.json

Usage

The HTTP API is accessible through the https://{app_id}.cloud.ditto.live/api/v4/store/[method] endpoint.

Endpoints

  • /api/v4/store/write
  • /api/v4/store/findbyid
  • /api/v4/store/find
  • /api/v4/store/count

Write

The write command is used to upsert, update, and remove documents from the big peer. These changes will then replicate to all connected small peers.

Upsert

A full upsert example with curl that shows how to use the HTTP API to create or replace a document with explicit types. In this example, we create a friends key with a Register that is an array, and orderCount which is a counter.

curl -X POST 'https://{app_id}.cloud.ditto.live/api/v4/store/write' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer $API_KEY' \  --data-raw '{      "commands": [{        "method": "upsert",        "collection": "people",        "id": "123abc",        "value": {          "name": "John",          "friends": ["Susan"],          "orderCount": 5        },        "valueTypeOverrides": {          "orderCount": "counter"        }      }]  }'

To create and modify a mutable type such as Register Map or Counter in the HTTP API, you can annotate the value with the type you intend to use. Arrays are registers by default. That means you do not need to add register to the valueTypeOverrides payload, but you can if you want to be explicit.

In this example, We use the counter override by adding the following key to the payload:

"valueTypeOverrides": {  "orderCount": "counter",  "friends": "register"}
info

Can I issue a find query inside of a write command?

No. First, send a find, and then after a response, send an write request.

Update

The update subcommand further has subcommands: set, increment, and replaceWithCounter. All of these take arguments method, path, and value.

curl -s -X POST "https://{app_id}.cloud.ditto.live/api/v4/store/write" \  --header "Authorization: Bearer ${API_KEY}" \  --header 'Content-Type: application/json' \      -d '{        "commands": [{            "method": "update",            "collection": "orders",            "query": "quantity == 0",            "commands": [{                "method": "increment",                "path": "quantity",                "value": 1            }]        }] }'

Remove

Documents may be removed from the big peer and across the mesh of connected small peers with the remove command. Ditto is a distributed system, so document removal creates a "tombstone" document to mark a document as removed. For each document ID matching the query, one tombstone record is created and a Change Event is emitted. The total number of documents which may be deleted in a single request is limited to 1000.

Request:

curl -X POST 'https://{app_id}.cloud.ditto.live/api/v4/store/write' \  --header 'Authorization: Bearer $API_KEY' \  --header 'Content-Type: application/json' \  --data-raw '{    "commands": [{        "method": "remove",        "collection": "people",        "query": "name==\'John\'"     }]}'

FindByID

To find a single document by its unique ID, you can use /api/v4/store/findbyid. Note that you must include all fields of a compound document ID.

curl --location --request POST 'https://{app_id}.cloud.ditto.live/api/v4/store/findbyid' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer $API_KEY' \--data-raw '{  "collection": "people",  "id": "123abc"}'

Find

The find method is used to fetch the current version of multiple documents from the big peer. These documents will be returned in an arbitrary order unless a sort directive is provided as described below. Queries which target large collections and match thousands of documents may result in a Response Status Code of 408 due to a time out. Breaking down one large query into several more selective queries will generally resolve this problem. Also the set of matching documents is limited to 1000 by default. When you query for this data using /api/v4/store/find, you can optionally use the key serializedAs: latestValuesAndTypes to receive a response with each type specified:

Request:

curl -X POST 'https://{app_id}.cloud.ditto.live/api/v4/store/find' \  --header 'Content-Type: application/json' \  --header 'Authorization: Bearer $API_KEY' \  --data-raw '{    "collection": "people",    "query": "name==\'John\'",    "limit": 2,    "sort": [      {"property": "_id", "direction": "asc"}    ],    "serializedAs": "latestValuesAndTypes"}'

Response: 

{  "value": {    "_id": "123abc",    "fields": {      "name": {          "register": { "value": "John" },      },      "friends": {          "register": { "value": ["Susan"] },      },      "orderCount": {          "counter": { "value": 5 }      },    }  }}

For more examples, see the corresponding sections in the Concepts section for querying, writing, and remove.

info

Use default sorting behavior from HTTP API v3

HTTP API v4 has a breaking change from v3. HTTP API v4 no longer guarantees a sorting order by default. If you were using v3 HTTP API and want to maintain its sort order, add sort by _id ascending to your request, like so:

"sort": [   {"property": "_id", "direction": "asc"}]

Count

The count command can be used to count the number of documents matching a query expression at a moment in time on the big peer. This can be useful to determine if documents have synced to the big peer or to "test" how much data a subscription will sync to a small peer. Queries with both inline and $args are supported.

Request:

curl -X POST 'https://{app_id}.cloud.ditto.live/api/v4/store/count' \  --header 'Authorization: Bearer $API_KEY' \  --header 'Content-Type: application/json' \  --data-raw '{    "collection": "people",    "query": "name == \'John\'"}'

Distinct Values

POST https://{app_id}.cloud.ditto.live/api/v1/collections/<collection_name>/distinct_values

Query for the distinct values in a collection. Returns a single document containing the paths and their distinct values. Paths are specified as json arrays of strings. This query expects a body of json in the following format:

{  "filter": "true"  "paths": [    "widgets",    "nested.device_id",    "nested.tags[*]",    "nested",    "nested.tags"  ]}

Parameters

  • filter - The query used to select documents.
  • paths (list) - A list of DittoQl paths to get distinct values for. See Supported Paths section below.
  • timeout_millis (number, optional) - the timeout, in milliseconds

Supported paths

  • Field access. Eg. fieldA, fieldA.fieldB.
  • Array projection. Eg. fieldA.arrayB[*], fieldA.arrayB[*].fieldC.
  • No other access methods are supported.

Response

The response will contain an object where the keys are the requested paths (same format as the request) and their values are the unique values at the respective paths. Note that only primitive values are returned distinctly. Any arrays or objects present at the specified path will appear in the result as an empty array {} or object {} respectively.

HTTP/1.1 200 OKContent-Type: application/jsonX-DITTO-TXN-ID: 7{  "item": {    "widgets": [1, 2, 3],    "nested.device_id": ["device1", "device2"],    "nested.tags[*]": ["tag1", "tag2"],    "nested": [{}],    "nested.tags": [[]],  }}
New and Improved Docs

Ditto has a new documentation site at https://docs.ditto.live. This legacy site is preserved for historical reference, but its content is not guaranteed to be up to date or accurate.