Local HTTP API exposed by the Ditto Edge Server process running on-device or on an edge node. Provides endpoints for executing DQL queries, health checks, peer-presence status, and log retrieval. Supports configurable per-IP, per-API-key, and per-route rate limiting.
openapi: 3.1.0
info:
title: Operator Management API
description: A RESTful API that allows users to manage Big Peer apps and API keys.
license:
name: Ditto Binary License
identifier: Ditto Binary License
version: 1.0.0
servers:
- url: http://localhost:{port}
description: Local server
variables:
port:
default: '8080'
paths:
/namespace/{namespace}/bigPeer/{big_peer_name}/app:
get:
tags:
- Apps
summary: List Apps
description: Lists all apps associated with a particular Big Peer instance.
operationId: listApps
responses:
'200':
description: list of apps associated with a big peer instance
content:
application/json:
schema:
$ref: '#/components/schemas/ListResponse_App'
examples:
Apps:
value:
meta:
page: 1
size: 2
totalPages: 1
data:
- name: minimal
appId: ad349e91-3e4c-44bb-9278-fc5bb80239b5
- name: my-app
appId: cb692760-9786-44c3-b040-019bec5a1b77
post:
tags:
- Apps
summary: Create App
description: Creates an app associated with a particular Big Peer instance.
operationId: createApp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/App'
required: true
responses:
'200':
description: Big Peer app successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/App'
examples:
App:
value:
name: my-app
appId: cb692760-9786-44c3-b040-019bec5a1b77
'400':
description: app id is not unique
content:
application/json:
examples:
AppIdNotUnique:
summary: there is already an app with the same id, managed by this
big peer
'404':
description: Big Peer in URI params does not exist
content:
application/json:
examples:
BigPeerNotFound:
summary: big peer not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}:
get:
tags:
- Apps
summary: Get App
description: Retrieves details for a specific Big Peer app.
operationId: getApp
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/App'
examples:
App:
value:
name: my-app
appId: cb692760-9786-44c3-b040-019bec5a1b77
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: app not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
put:
tags:
- Apps
summary: Update App
description: Updates an existing Big Peer app's configuration.
operationId: updateApp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAppRequest'
required: true
responses:
'200':
description: App successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/App'
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: app not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
delete:
tags:
- Apps
summary: Delete App
description: Deletes a Big Peer app and all associated resources.
operationId: deleteApp
responses:
'200':
description: Big Peer app successfully deleted
content:
application/json:
schema:
default: null
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: app not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
patch:
tags:
- Apps
summary: Update App
description: Updates an existing Big Peer app's configuration.
operationId: updateApp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAppRequest'
required: true
responses:
'200':
description: App successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/App'
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: app not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/apiKey:
get:
tags:
- API Keys
summary: List API Keys
description: Lists all API keys associated with a Big Peer app.
operationId: listApiKeys
responses:
'200':
description: list of api keys associated with a big peer app
content:
application/json:
schema:
$ref: '#/components/schemas/ListResponse_ApiKey'
examples:
ApiKeys:
value:
meta:
page: 1
size: 1
totalPages: 1
data:
- name: my-key
expiresAt: '2100-04-13T12:00:00Z'
permissions:
remoteQuery: true
read:
everything: true
queriesByCollection: {}
write:
everything: true
queriesByCollection: {}
description: null
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: app not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
post:
tags:
- API Keys
summary: Create API Key
description: Creates a new API key for authenticating against the Big Peer HTTP
API.
operationId: createApiKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
required: true
responses:
'200':
description: Plaintext API key.
content:
application/json:
schema:
type: string
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
InvalidApiKeyExpiryDate:
summary: attempt to create api key with past expiry date
'404':
description: app specified in URI params does not exist
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/apiKey/{api_key_name}:
get:
tags:
- API Keys
summary: Get API Key
description: Retrieves details for a specific API key.
operationId: getApiKey
responses:
'200':
description: api key successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: api key not found
content:
application/json:
examples:
ApiKeyNotFound:
summary: api key not found
delete:
tags:
- API Keys
summary: Delete API Key
description: Deletes an API key.
operationId: deleteApiKey
responses:
'200':
description: ''
content:
application/json:
schema:
default: null
'400':
description: bad request
content:
application/json:
examples:
AppNameMismatch:
summary: app name in api key label doesn't match uri parameter
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: api key not found
content:
application/json:
examples:
ApiKeyNotFound:
summary: api key key not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/bigPeerReplication:
post:
tags:
- Apps
- BigPeerReplication
summary: Create Replication
description: Creates a new Big Peer to Big Peer replication for an app.
operationId: createReplication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BigPeerReplication'
required: true
responses:
'200':
description: Big Peer replication successfully created for app
content:
application/json:
schema:
$ref: '#/components/schemas/BigPeerReplication'
'404':
description: Big Peer in URI params does not exist
content:
application/json:
examples:
BigPeerNotFound:
summary: big peer not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/bigPeerReplication/{replication_name}:
get:
tags:
- Apps
- BigPeerReplication
summary: Get Replication
description: Retrieves details for a specific Big Peer replication.
operationId: getReplication
responses:
'200':
description: big peer replication successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/BigPeerReplication'
'400':
description: bad request
content:
application/json:
examples:
AppNameMismatch:
summary: app in big peer replication label doesn't match uri parameter
'404':
description: big peer replication not found
content:
application/json:
examples:
BigPeerReplicationNotFound:
summary: big peer replication not found
put:
tags:
- Apps
- BigPeerReplication
summary: Update Replication
description: Updates an existing Big Peer replication's configuration.
operationId: updateReplication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBigPeerReplicationRequest'
required: true
responses:
'200':
description: Big Peer replication successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/BigPeerReplication'
'400':
description: bad request
content:
application/json:
examples:
AppNameMismatch:
summary: app in big peer replication label doesn't match uri parameter
'404':
description: big peer replication not found
content:
application/json:
examples:
BigPeerReplicationNotFound:
summary: big peer replication not found
delete:
tags:
- Apps
- BigPeerReplication
summary: Delete Replication
description: Deletes a Big Peer replication.
operationId: deleteReplication
responses:
'200':
description: ''
content:
application/json:
schema:
default: null
'400':
description: bad request
content:
application/json:
examples:
AppNameMismatch:
summary: app name in big peer replication label doesn't match uri
parameter
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: big peer replication not found
content:
application/json:
examples:
BigPeerReplicationNotFound:
summary: big peer replication not found
patch:
tags:
- Apps
- BigPeerReplication
summary: Update Replication
description: Updates an existing Big Peer replication's configuration.
operationId: updateReplication
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBigPeerReplicationRequest'
required: true
responses:
'200':
description: Big Peer replication successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/BigPeerReplication'
'400':
description: bad request
content:
application/json:
examples:
AppNameMismatch:
summary: app in big peer replication label doesn't match uri parameter
'404':
description: big peer replication not found
content:
application/json:
examples:
BigPeerReplicationNotFound:
summary: big peer replication not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/dataBridge:
get:
tags:
- Data Bridge
summary: List Data Bridges
description: Lists all data bridges (CDC or MongoDB Connector) associated with
a Big Peer app.
operationId: listDataBridges
responses:
'200':
description: List of data bridges for the app
content:
application/json:
schema:
$ref: '#/components/schemas/ListResponse_DataBridgeObject'
'404':
description: App not found
content:
application/json:
examples:
AppNotFound:
summary: app not found
post:
tags:
- Data Bridge
summary: Create Data Bridge
description: Creates a new data bridge for CDC or MongoDB Connector integration.
operationId: createDataBridge
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataBridgeRequest'
required: true
responses:
'201':
description: Data bridge successfully created for app
content:
application/json:
schema:
$ref: '#/components/schemas/DataBridgeObject'
'400':
description: Bad request
content:
application/json:
examples:
WebhookNotSupported:
summary: webhook destinations are not supported
'404':
description: App not found
content:
application/json:
examples:
AppNotFound:
summary: app not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/dataBridge/{data_bridge_name}:
get:
tags:
- Data Bridge
summary: Get Data Bridge
description: Retrieves details for a specific data bridge.
operationId: getDataBridge
responses:
'200':
description: Data bridge details
content:
application/json:
schema:
$ref: '#/components/schemas/DataBridgeObject'
'404':
description: App or data bridge not found
content:
application/json:
examples:
AppNotFound:
summary: app not found
DataBridgeNotFound:
summary: data bridge not found
delete:
tags:
- Data Bridge
summary: Delete Data Bridge
description: Deletes a data bridge.
operationId: deleteDataBridge
responses:
'204':
description: Data bridge successfully deleted
content:
application/json:
schema:
default: null
'404':
description: App or data bridge not found
content:
application/json:
examples:
AppNotFound:
summary: app not found
DataBridgeNotFound:
summary: data bridge not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/provider:
post:
tags:
- Apps
summary: Add Auth Provider
description: Adds or updates an auth provider for a Big Peer app. If a provider
with the same name already exists, it will be overwritten with the new provider
config.
operationId: createProvider
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddProviderRequest'
required: true
responses:
'200':
description: Auth provider successfully added or updated.
content:
application/json:
schema:
$ref: '#/components/schemas/App'
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: app not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
/namespace/{namespace}/bigPeer/{big_peer_name}/app/{app_name}/provider/{provider_name}:
post:
tags:
- Apps
summary: Delete Auth Provider
description: Deletes an auth provider from a Big Peer app.
operationId: deleteProviderPost
responses:
'200':
description: Auth provider successfully deleted
content:
application/json:
schema:
default: null
'400':
description: bad request
content:
application/json:
examples:
BigPeerNameMismatch:
summary: big peer in app label doesn't match uri parameter
'404':
description: resource not found
content:
application/json:
examples:
AppNotFound:
summary: big peer app not found
AuthProviderNotFound:
summary: app auth provider not found
components:
schemas:
AddProviderRequest:
type: object
required:
- name
- config
properties:
config:
oneOf:
- type: object
title: TokenWebhook
description: Token webhook authentication provider. Validates device tokens
by calling a user-provided webhook URL. The webhook receives the token
and returns the authenticated user information and permissions.
properties:
type:
type: string
enum:
- webhookUrl
webhookUrl:
type: string
format: uri
- type: object
title: Anonymous
description: This is a configuration setting for an anonymous provider.
This contains what permissions to give anonymous users, how long their
sessions should last and a shared token. The purpose of the shared token
is to prevent random scanners on the internet from grabbing tokens.
The token isn't considered private or secure since it will be embedded
in a client software.
required:
- permission
- sessionLength
- sharedToken
- type
properties:
permission:
$ref: '#/components/schemas/Permission'
sessionLength:
type: integer
format: u-int32
description: Session length in seconds. Minimum is 1 second.
minimum: 1
sharedToken:
type: string
type:
type: string
enum:
- anonymous
title: ProviderConfig
description: This describes the document stored in the __auth_config with
the _id of auth_config. It describes the auth providers configured for
a BigPeer App.
name:
type: string
ApiKey:
type: object
required:
- name
- expiresAt
- permissions
properties:
description:
type:
- string
- 'null'
example: API key used for staging environment.
expiresAt:
type: string
format: date-time
example: '2100-04-13T12:00:00Z'
name:
type: string
title: Dns1123Label
description: "RFC 1123 DNS labels used for most Kubernetes resource names.\
\ Some resource types require their names to follow the DNS label standard\
\ as defined in [RFC 1123][rfc1123].\n This means the name\
\ must:\n * contain at most 63 characters * contain only\
\ lowercase alphanumeric characters or '-' * start with an alphanumeric\
\ character\n * end with an alphanumeric character\n \
\ [rfc1123]: https://tools.ietf.org/html/rfc1123"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
permissions:
type: object
title: Permission
description: Set of permissions granted to a particular API key or device
token.
required:
- read
- write
properties:
qlVersion:
type: integer
format: u-int8
description: What query language version are the queries written in?
If 1, use DQL. If 0, use legacy query builder. Other numbers are not
valid. Defaults to 0.
default: 0
enum:
- 0
- 1
read:
$ref: '#/components/schemas/PermissionRules'
description: The set of read permissions granted
remoteQuery:
type: boolean
description: Can this initiate remote queries? In addition to this,
remote queries also require full read permission.
default: false
write:
$ref: '#/components/schemas/PermissionRules'
description: The set of write permissions granted
App:
type: object
required:
- name
properties:
appId:
type: string
title: AppId
format: uuid
description: UUID used to identify a BigPeerApp resource
authProviders:
type: object
title: AuthProviders
description: Auth providers associated with a BigPeer App, to be used when
authenticating devices against BigPeer Subscription.
additionalProperties:
$ref: '#/components/schemas/ProviderConfig'
name:
type: string
title: Dns1123Label
description: "RFC 1123 DNS labels used for most Kubernetes resource names.\
\ Some resource types require their names to follow the DNS label standard\
\ as defined in [RFC 1123][rfc1123].\n This means the name\
\ must:\n * contain at most 63 characters * contain only\
\ lowercase alphanumeric characters or '-' * start with an alphanumeric\
\ character\n * end with an alphanumeric character\n \
\ [rfc1123]: https://tools.ietf.org/html/rfc1123"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
BigPeerReplication:
type: object
required:
- name
properties:
connections:
type:
- array
- 'null'
items:
type: string
format: uri
description: 'A set of connection addresses of other Big Peer instances.
Each connection address should point to the Big Peer replication server
dedicated to the
same app ID.
The set is allowed to be empty. In this case, it''s the remote Big Peer''s
responsibility to
initiate the connection.'
example:
- big-peer-2.ditto.svc.cluster.local:4040
uniqueItems: true
name:
type: string
title: Dns1123Label
description: "RFC 1123 DNS labels used for most Kubernetes resource names.\
\ Some resource types require their names to follow the DNS label standard\
\ as defined in [RFC 1123][rfc1123].\n This means the name\
\ must:\n * contain at most 63 characters * contain only\
\ lowercase alphanumeric characters or '-' * start with an alphanumeric\
\ character\n * end with an alphanumeric character\n \
\ [rfc1123]: https://tools.ietf.org/html/rfc1123"
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
queriesByCollection:
type:
- object
- 'null'
description: 'Mapping from collection name to a list of DQL subscriptions
queries.
This contains the data that the Big Peer instance will subscribe to, for
the given app, in
the context of Big Peer replication.
If empty, this Big Peer instance will not subscribe to any data so no
data will be
replicated to it.'
additionalProperties:
type: array
items:
type: string
propertyNames:
type: string
example:
cars:
- 'true'
DataBridge:
type: object
required:
- name
- bridge
properties:
bridge:
oneOf:
- type: object
title: Kafka
properties:
kafka:
type: object
properties:
extraAcls:
type: array
items:
type: object
description: Kafka ACL rule following the Strimzi KafkaUser
ACL schema
description: Extra ACLs that you may want to add to the KafkaUser
that grants permissions to read from the data bridge Kafka topic.
Follows the Strimzi KafkaUser authorization ACL schema.
source:
type: array
items:
type: object
title: FilteredSource
description: Filtered source defining collection and DQL query
required:
- collection
- query
properties:
collection:
type: string
description: 'Name of the collection against which the query
will be run. Example: ''cars'''
query:
type: string
description: 'DQL query to filter the documents. Example:
"status = ''completed'' AND type = ''order''"'
description: Array of filtered sources defining the data you'd
like to stream. Each source specifies a collection and DQL query
to filter documents. When absent or empty, it will stream every
change to any document.
streamType:
type: string
description: 'Determines which modifications will be applied to
incoming data structures. If you don''t know what this is, then
you don''t need to set it. Options: ''heartbeat'', ''typed'',
or ''untyped'' (default).'
default: untyped
enum:
- heartbeat
- typed
- untyped
topicPartitions:
type: integer
description: 'Number of topic partitions (defaults to 10, min:
1, max: 1000)'
default: 10
maximum: 1000
minimum: 1
- type: object
title: MongoConnector
properties:
mongoConnector:
type: object
required:
- connectionSecret
- database
- collections
properties:
collections:
type: object
description: Map of collections to sync, where the key is the
collection name
additionalProperties:
type: object
title: MongoCollection
description: MongoDB collection configuration for sync
required:
- fields
- initialSync
- mode
properties:
dittoTypes:
type: object
description: CRDT type information for specific field paths
properties:
settableCounters:
type: array
items:
type: st
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ditto-live/refs/heads/main/openapi/ditto-live-operator-api-openapi.yml