Eclipse Ditto™ HTTP API
v2Base URLs
https://ditto.eclipseprojects.io/online Ditto Sandbox/local DittoThe HTTP API follows REST conventions and provides a resource-based interface for managing Things, Policies and Connections. You send standard HTTP requests (GET, PUT, POST, PATCH, DELETE) and receive JSON responses. Use it for request and response interactions: managing Things, Features, Policies and Connections, searching across Things, and sending messages to or from devices. For real-time events, Ditto also offers a WebSocket API and Server-Sent Events; see the API overview.
The Eclipse Ditto HTTP API uses response status codes (see RFC 7231) to indicate whether a specific request has been successfully completed, or not.
The information Ditto provides additionally to the status code (e.g. in API docs, or error codes like. "things:thing.tooLarge") might change without advance notice. These are not be considered as official API, and must therefore not be applied in your applications or tests.
Authentication
NginxBasichttpEclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
Scheme: basic
BearerhttpA JSON Web Token issued by a supported OAuth 2.0 Identity Provider.
Scheme: bearer (JWT)
OpenIDConnectopenIdConnectOpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
DevOpsBasichttpEclipse Ditto devops user (devops) + password (foobar)
Scheme: basic
DevOpsBearerhttpA JSON Web Token issued by a supported OAuth 2.0 Identity Provider for the Eclipse Ditto devops user.
Scheme: bearer (JWT)
Things
Manage every thing
- GETRetrieve visible things or things with specified IDs
- POSTCreate a new thing
- GETRetrieve a specific thing
- PUTCreate or update a thing with a specified ID
- DELETEDelete a specific thing
- PATCHCreate or patch a thing with a specified ID
- POSTUpdate the definition of an existing Thing
- GETRetrieve the definition of a specific thing
- PUTCreate or update the definition of a specific thing
- DELETEDelete the definition of a specific thing
- PATCHPatch the definition of a specific thing
- GETRetrieve the policy ID of a thing
- PUTUpdate the policy ID of a thing
- PATCHPatch the policy ID of a thing
- GETList all attributes of a specific thing
- PUTCreate or update all attributes of a specific thing at once
- DELETEDelete all attributes of a specific thing at once
- PATCHPatch all attributes of a specific thing
- GETRetrieve a specific attribute of a specific thing
- PUTCreate or update a specific attribute of a specific thing
- DELETEDelete a specific attribute of a specific thing
- PATCHPatch a specific attribute of a specific thing
Features
Structure the features of your things
- GETList all features of a specific thing
- PUTCreate or modify all features of a specific thing at once
- DELETEDelete all features of a specific thing
- PATCHPatch all features of a specific thing
- GETRetrieve a specific feature of a specific thing
- PUTCreate or modify a specific feature of a specific thing
- DELETEDelete a specific feature of a specific thing
- PATCHPatch a specific feature of a specific thing
- GETList the definition of a feature
- PUTCreate or update the definition of a feature
- DELETEDelete the definition of a feature
- PATCHPatch the definition of a feature
- GETList all properties of a feature
- PUTCreate or update all properties of a feature at once
- DELETEDelete all properties of a feature
- PATCHPatch all properties of a feature
- GETRetrieve a specific property of a feature
- PUTCreate or update a specific property of a feature
- DELETEDelete a specific property of a feature
- PATCHPatch a specific property of a feature
- GETList all desired properties of a feature
- PUTCreate or update all desired properties of a feature at once
- DELETEDelete all desired properties of a feature
- PATCHPatch all desired properties of a feature
- GETRetrieve a specific desired property of a feature
- PUTCreate or update a specific desired property of a feature
- DELETEDelete a specific desired property of a feature
- PATCHPatch a specific desired property of a feature
Policies
Control access to your things
- GETRetrieve a specific policy
- PUTCreate or update a policy with a specified ID
- DELETEDelete a specific policy
- POSTActivate subjects for this policy derived from the token
- POSTDeactivate subjects for this policy derived from the token
- GETRetrieve the entries of a specific policy
- PUTModify the entries of a specific policy
- GETRetrieve the entries of a specific Label of a specific policy
- PUTCreate or modify the entries of a specific Label of a specific policy
- DELETEDelete the entries of a specific Label of a specific policy
- POSTActivate a subject for this policy entry derived from the token
- POSTDeactivate a subject for this policy entry derived from the token
- GETRetrieve all Subjects for a specific Label of a specific policy
- PUTCreate or modify all Subjects for a specific Label of a specific policy
- GETRetrieve one specific Subject for a specific Label of a specific policy
- PUTCreate or modify one specific Subject for a specific Label of a specific policy
- DELETEDelete one specific Subject for a specific Label of a specific policy
- GETRetrieve all Resources for a specific Label of a specific policy
- PUTCreate or modify all Resources for a specific Label of a specific policy
- GETRetrieve one specific Resource for a specific Label of a specific policy
- PUTCreate or modify one specific Resource for a specific Label of a specific policy
- DELETEDelete one specific Resource for a specific Label of a specific policy
- GETRetrieve the allowed import additions for a specific policy entry
- PUTModify the allowed import additions for a specific policy entry
- GETRetrieve the namespace patterns for a specific policy entry
- PUTModify the namespace patterns for a specific policy entry
- GETRetrieve the importable type for a specific policy entry
- PUTModify the importable type for a specific policy entry
- GETRetrieve the imports of a specific policy
- PUTModify the imports of a specific policy
- DELETEDelete all imports of a specific policy
- GETRetrieve a specific policy import.
- PUTCreate or modify a specific policy import of a policy.
- DELETEDelete a specific policy import.
- GETRetrieve the entries of a specific policy import
- PUTModify the entries of a specific policy import
- GETRetrieve the transitive resolution policy IDs of a specific policy import
- PUTModify the transitive resolution policy IDs of a specific policy import
- GETRetrieve the references of a specific policy entry
- PUTModify the references of a specific policy entry
- DELETERemove all references from a specific policy entry
- GETRetrieve information about the current caller
- POSTCheck permissions for specified entities
Things-Search
Find every thing
Messages
Talk with your things
CloudEvents
Process CloudEvents in Ditto
Connections
Manage connections
- GETRetrieve all connections
- POSTCreate a new connection
- GETRetrieve a specific connection
- PUTCreate or update a connection with a specified ID
- DELETEDelete a specific connection
- POSTSend a command to a specific connection
- GETRetrieve status of a specific connection
- GETRetrieve metrics of a specific connection
- GETRetrieve logs of a specific connection
WoT
WoT (Web of Things) Discovery endpoints
Devops
Devops APIs to manage log levels and configuration in runtime and send piggyback command
- GETRetrieve all currently configured log levels
- PUTUpdate log levels
- GETRetrieve currently configured log levels for a specific module
- PUTUpdate log levels for a specific module
- GETRetrieve the configuration at the specified path parameter
- GETRetrieving the configuration of a specific service instance.
- POSTSend a piggyback command
- POSTSend a piggyback command to a specific service
- POSTSend a piggyback command to a specific instance of service
- GETGet the WoT validation config
- PUTUpdate the WoT validation config
- DELETEDelete the WoT validation config
- GETGet the merged WoT validation config
- GETList all dynamic WoT validation config sections
- GETGet a dynamic WoT validation config section by scopeId
- PUTCreate or update a dynamic WoT validation config section
- DELETEDelete a dynamic WoT validation config section
Models
- Error
- AdvancedError
- AttributesAn arbitrary JSON object describing the attributes of a thing.
- DefinitionA single fully qualified identifier of a definition in the form '<namespace>:<name>:<version>' or a valid HTTP(s) URL
- FeatureDefinitionThe definitions of a feature.
- FeaturePropertiesAn arbitrary JSON object describing the properties of a feature.
- FeatureDesiredPropertiesAn arbitrary JSON object describing the desired properties of a feature.
- Feature
- SearchResultThings
- SearchResultThingsCount
- NewThing
- PatchThing
- Thing
- MigrateThingDefinitionRequestJSON payload to migrate the definition of a Thing.
- MigrateThingDefinitionResponseResponse payload after applying or simulating a migration to a Thing.
- NewPolicyPolicy consisting of policy entries
- PolicyPolicy consisting of policy entries
- PolicyImportsPolicy imports containing one policy import for each key. The key is the policy ID of the referenced policy.
- PolicyImportSingle policy import defining which policy entries of the referenced policy are imported.
- ImportableControls the import behavior of this policy entry i.e. whether this policy entry is implicitly, explicitly or never imported when referenced from another policy. * `implicit` (default): the policy entry is imported without being listed in the importing policy individually * `explicit`: the policy entry is only imported if it is listed in the importing policy * `never`: the policy entry is not imported, regardless of being listed in the importing policy If the field is not specified, default value is `implicit`.
- PolicyEntriesPolicy entries containing one policy entry for each arbitrary `label` key
- PolicyEntrySingle policy entry. Both `subjects` and `resources` are optional — they default to empty when absent. An entry may define `references` to inherit subjects, resources, and namespaces from other entries (local or imported).
- SubjectsA SubjectEntry defines who is addressed.
- SubjectEntrySingle (Authorization) Subject entry holding its type.
- Resources(Authorization) Resources containing one ResourceEntry for each `type:path` key, `type` being one of the following `thing`, `policy`, `message`.
- ResourceEntrySingle (Authorization) Resource entry defining permissions per effect. Allowed effects are `grant` and `revoke`.
- PermissionA Permission allows a certain action on an entity
- AllowedAdditionsDefines which types of additions are allowed when this entry is referenced by other entries via `references`. Semantics: * Field absent (omitted) — no restriction; the referencing entry's own subjects, resources, and namespaces are merged in as usual. This is the upgrade-friendly default. * Field present and empty (`[]`) — no additions allowed; only the referenced entry's content is effective. * Field present with values — only the listed kinds of additions survive on the referencing entry. This field is enforced as a runtime filter, not as a write-time policy contract: a referencing entry that declares own subjects/resources/namespaces not permitted here can still be persisted, but the disallowed own additions are silently stripped at enforcement time. The same filter applies whether the reference is local (within the same policy) or an import reference. * `subjects` — allows referencing entries to add additional subjects on top of this entry * `resources` — allows referencing entries to add additional resources on top of this entry * `namespaces` — allows referencing entries to add additional namespace patterns on top of this entry
- TransitiveImportsList of policy IDs from the imported policy's own imports that should be resolved transitively before extracting entries. This enables multi-level import chains where a template policy defines resources and an intermediate policy defines entries with "references" that add local subjects. Each entry is the policy ID of a policy that the directly imported policy itself imports from. Only the listed policy IDs are resolved — this is an explicit whitelist, not a recursive flag.
- ReferencesAn optional list of references to other policy entries. Each reference points to an entry either in the same policy (local reference) or in an imported policy (import reference). When set, subjects, resources, and namespaces from the referenced entries are additively merged into this entry. * Import reference: contains both `entry` (the label) and `import` (the policy ID of the imported policy) * Local reference: contains only `entry` (the label of another entry in the same policy)
- SubjectAnnouncementSettings for announcements to be made about the subject.
- FeaturesList of features where the key represents the `featureId` of each feature. The `featureId` key must be unique in the list.
- Connection
- NewConnection
- SourcesThe subscription sources of this connection
- SourceA subscription source subscribed by this connection
- TargetsThe publish targets of this connection
- TargetA publish target served by this connection
- ConnectionTypeThe type of a connection
- ConnectivityStatusThe status of a connection or resource
- PayloadMappingDefinitionsList of mapping definitions where the key represents the ID of each mapping that can be used in sources and targets to reference a mapping.
- PayloadMappingDefinitionA mapping definition consisting of the used mappingEngine and the options required by this engine.
- MappingContextMappingContext to apply in this connection containing JavaScript scripts mapping from external messages to internal Ditto Protocol messages. Usage of MappingContext is deprecated, use PayloadMappingDefinitions instead.
- ConnectionStatusStatus of a connection and its resources
- ResourceStatusThe status of a single resource (e.g. a client or a source/target resource)
- ConnectionMetricsMetrics of a connection
- OverallConnectionMetricsOverall metrics of the connection
- SourceMetricsSource metrics of the connection
- TargetMetricsTarget metrics of the connection
- InboundMetricsMetrics of an inbound (e.g. a Source) resource
- OutboundMetricsMetrics of an outbound (e.g. a Target) resource
- TypedMetricMetrics of a single metric `type` containing "success" and "failure" metrics
- SingleMetricContains a single metric consisting of several time intervals and counter values for those intervals including the last message date.
- ConnectionLogsLog entries of a connection.
- LogEntryRepresents a log entry for a connection.
- LogCategoryA category to which the log entry can be referred to.
- LogTypeThe type of a log entry describing during what kind of activity the entry was created.
- LogLevelEscalation level of a log entry.
- WhoAmIContains information about the current user and the auth subjects available for the used authentication.
- WhoAmISubjectAn auth subject that can be used to provide access for a caller (e.g. in subject entries of policies).
- WotThingDescriptionA WoT Thing Description version 1.1
- RetrieveConfig
- RetrieveLoggingConfig
- ModuleModule
- LoggingUpdateFields
- UpdatedLogLevelDetails of logging configuration
- ModuleUpdatedLogLevelModule that has been updated
- ResultUpdateRequest
- ModuleConfigServiceModule
- ResultConfigServiceDetails of specific service instance.
- RetrieveConfigService
- BasePiggybackCommandRequestSchema
- PiggybackManagingBackgroundCleanup
- SearchFilterProperty #### Filter predicates: * ```eq({property},{value})``` (i.e. equal to the given value) * ```ne({property},{value})``` (i.e. not equal to the given value) * ```gt({property},{value})``` (i.e. greater than the given value) * ```ge({property},{value})``` (i.e. equal to the given value or greater than it) * ```lt({property},{value})``` (i.e. lower than the given value or equal to it) * ```le({property},{value})``` (i.e. lower than the given value) * ```in({property},{value},{value},...)``` (i.e. contains at least one of the values listed) * ```like({property},{value})``` (i.e. contains values similar to the expressions listed) * ```ilike({property},{value})``` (i.e. contains values similar and case insensitive to the expressions listed) * ```exists({property})``` (i.e. all things in which the given path exists) * ```empty({property})``` (i.e. all things in which the given path is absent, null, an empty array, an empty object or an empty string) Note: When using filter operations, only things with the specified properties are returned. For example, the filter `ne(attributes/owner, "SID123")` will only return things that do have the `owner` attribute. #### Logical operations: * ```and({query},{query},...)``` * ```or({query},{query},...)``` * ```not({query})``` #### Examples: * ```eq(attributes/location,"kitchen")``` * ```ge(thingId,"myThing1")``` * ```gt(_created,"2020-08-05T12:17")``` * ```exists(features/featureId)``` * ```empty(attributes/tags)``` * ```and(eq(attributes/location,"kitchen"),eq(attributes/color,"red"))``` * ```or(eq(attributes/location,"kitchen"),eq(attributes/location,"living-room"))``` * ```like(attributes/key1,"known-chars-at-start*")``` * ```like(attributes/key1,"*known-chars-at-end")``` * ```like(attributes/key1,"*known-chars-in-between*")``` * ```like(attributes/key1,"just-som?-char?-unkn?wn")``` The `like` filters with the wildcard `*` at the beginning can slow down your search request.
- NamespacePropertyA comma-separated list of namespaces. This list is used to limit the query to things in the given namespaces only. #### Examples: * `?namespaces=com.example.namespace` * `?namespaces=com.example.namespace1,com.example.namespace2`
- ConfigOverridesConfig overrides for a dynamic config section.
- ValidationContextValidation context for dynamic config section.
- ThingValidationConfigThing validation config.
- FeatureValidationConfigFeature validation config.
- DynamicValidationConfigDynamic config section for request/response.
- WotValidationConfigWoT validation configuration object.