Connections

Create or update a connection with a specified ID

PUT
https://ditto.eclipseprojects.io/api/2/connections/{connectionId}

Update the connection identified by the connectionId path parameter.

Body

application/json
namestring

The name of the connection

connectionTypeConnectionTypeamqp-091amqp-10http-pushmqttmqtt-5kafka,honorequired

The type of a connection

connectionStatusConnectivityStatusopenclosedfailedmisconfiguredunknownrequired

The status of a connection or resource

uristringrequired

The URI of the connection

sourcesArray<Source>required

The subscription sources of this connection

Show child attributes

A subscription source subscribed by this connection

addressesArray<string>

The source addresses this connection consumes messages from. The "telemetry", "events", "command_response" aliases should be used for connections of type "hono".

consumerCountinteger1

The number of consumers that should be attached to each source address

qosinteger

Maximum Quality-of-Service level to request when subscribing for messages

authorizationContextArray<string>

The authorization context defines all authorization subjects associated for this source

enforcementobject

Defines an enforcement for this source to make sure that a device can only access its associated Thing.

Show child attributes
inputstringrequired

The input value of the enforcement that should identify the origin of the message (e.g. a device id). You can use placeholders within this field depending on the connection type. E.g. for AMQP 1.0 connections you can use {{ header:[any-header-name] }} to resolve the value from a message header.

Example
{{ header:device_id }}
filtersArray<string>required

An array of filters. One of the defined filters must match the input value from the message otherwise the message is rejected.

acknowledgementRequestsobject

Contains requests to acknowledgements which must be fulfilled before a message consumed from this source is technically settled/ACKed at the e.g. message broker.

Show child attributes
includesArray<string>required

Acknowledgement requests to be included for each message consumed by this source.

filterstring

Optional filter to be applied to the requested acknowledgements - takes an fn:filter() function expression

Example
[
  "fn:filter(header:qos,'ne',0)"
]
payloadMappingArray<string>

A list of payload mappings that are applied to messages received via this source. If no payload mapping is specified the standard Ditto mapping is used as default.

headerMappingobject

Ditto protocol headers computed from external headers and certain properties of the Ditto protocol messages created by payload mapping.

replyTargetobject

Configuration for sending responses of incoming commands.

Show child attributes
enabledboolean

Whether reply target is enabled.

addressstringrequired

The target address where responses of incoming commands from the parent source are published to. The following placeholders are allowed within the target address:

  • Thing ID: {{ thing:id }}

  • Thing Namespace: {{ thing:namespace }}

  • Thing Name: {{ thing:name }} (the part of the ID without the namespace)

  • Ditto protocol topic attribute: {{ topic:[topic-placeholder-attr] }}

  • Ditto protocol header value: {{ header:[any-header-name] }}

If placeholder resolution fails for a response, then the response is dropped. NOTE Use "command" alias for connections of type "hono".

Example
[
  "{{ header:device_id }}",
  "{{ source:address }}"
]
headerMappingobject

External headers computed from headers and other properties of Ditto protocol messages.

expectedResponseTypesArray<string>responseerrornack

Contains a list of response types that should be published to the reply target.

targetsArray<Target>required

The publish targets of this connection

Show child attributes

A publish target served by this connection

addressstring

The target address where events, commands and messages are published to. The following placeholders are allowed within the target address:

  • Thing ID: {{ thing:id }}

  • Thing Namespace: {{ thing:namespace }}

  • Thing Name: {{ thing:name }} (the part of the ID without the namespace) NOTE Use "command" alias for connections of type "hono".

topicsArray<string>_/_/things/twin/events_/_/things/live/commands_/_/things/live/events_/_/things/live/messages_/_/policies/announcements_/_/connections/announcements

The topics to which this target is registered for

qosinteger

Maximum Quality-of-Service level to request when subscribing for messages

authorizationContextArray<string>

The authorization context defines all authorization subjects associated for this target

issuedAcknowledgementLabelstring

The optional label of an acknowledgement which should automatically be issued by this target based on the technical settlement/ACK the connection channel provides.

payloadMappingArray<string>

A list of payload mappings that are applied to messages sent via this target. If no payload mapping is specified the standard Ditto mapping is used as default.

headerMappingobject

External headers computed from headers and other properties of Ditto protocol messages.

specificConfigobject

Configuration which is only applicable for a specific connection type

clientCountnumber

How many clients on different cluster nodes should establish the connection

failoverEnabledboolean

Whether or not failover is enabled for this connection

validateCertificatesboolean

Whether or not to validate server certificates on connection establishment

mappingDefinitionsPayloadMappingDefinitions

List of mapping definitions where the key represents the ID of each mapping that can be used in sources and targets to reference a mapping.

Show child attributes
[key: string]PayloadMappingDefinition

A mapping definition consisting of the used mappingEngine and the options required by this engine.

Show child attributes
mappingEnginestringrequired

The mapping engine used to process incoming and outgoing messages. Available mapping engines are JavaScript, Normalized, ConnectionStatus, RawMessage, Ditto, ImplicitThingCreation, and UpdateTwinWithLiveResponse.

optionsobjectrequired

Configuration options specific to the used mapping engine:

JavaScript

  • incomingScript (string, required): The mapping script for incoming messages
  • outgoingScript (string, required): The mapping script for outgoing messages
  • loadBytebufferJS (boolean, optional): Whether or not ByteBufferJS library should be included (default: false)
  • loadLongJS (boolean, optional): Whether or not LongJS library should be included (default: false)

Normalized

  • fields (string, optional): Comma separated list of fields included in the normalized message (default: all fields included)

ConnectionStatus

  • thingId (string, required): The ID of the thing
  • featureId (string, optional): The ID of the modified feature (default: ConnectionStatus)

RawMessage

  • outgoingContentType (string, optional): The fallback content type for outgoing messages.
  • incomingMessageHeaders (object, optional): The fallback headers for incoming messages containing the necessary information to map them to message commands and responses. The relevant header keys are: content-type, ditto-message-subject, ditto-message-direction, ditto-message-thing-id, ditto-message-feature-id and status. The header values may contain placeholder expressions.

Ditto

  • no options required

ImplicitThingCreation

  • thing (object, required): The template of the thing to be implicitly created

UpdateTwinWithLiveResponse

  • dittoHeadersForMerge (object, optional): The Ditto headers to use for constructing the "merge thing" command for updating the twin, may for example add a condition to apply in order to update the twin (default ditto headers: response-required: false, if-match: "*").
incomingConditionsobject

Optional conditions to be checked before applying the mapping engine to inbound messages. Can use placeholders and functional expressions.

outgoingConditionsobject

Optional conditions to be checked before applying the mapping engine to outbound messages. Can use placeholders and functional expressions.

mappingContextMappingContextdeprecated

MappingContext 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.

Show child attributes
incomingScriptstringrequired

The mapping script for incoming messages

outgoingScriptstringrequired

The mapping script for outgoing messages

loadBytebufferJSbooleanrequired

Whether or not ByteBufferJS library should be included

loadLongJSbooleanrequired

Whether or not LongJS library should be included

sshTunnelobject

The configuration of a local SSH port forwarding used to tunnel the connection to the actual endpoint.

Show child attributes
enabledbooleanrequired

Whether the tunnel is enabled

Example
true
uristringrequired

The URI of the SSH host in the format ssh://[host]:[port].

Example
ssh://some.host:2222
credentialsobjectrequired

The credentials used to authenticate at the SSH host. Password and public key authentication are supported.

Show child attributes
typestringpasswordpublic-keyrequired

The type of credentials used to authenticate. Either password or public-key.

Example
password
usernamestringrequired

The username used for the authentication.

Example
user42
passwordstring

The password used for authentication when credentials type password is used.

Example
secret!
publicKeystring

Public key in PEM base64-encoded format using X.509 syntax. This field is required for credentials type public-key.

Example
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
privateKeystring

Private key in PEM base64-encoded format using PKCS #8 syntax. This field is required for credentials type public-key.

Example
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
validateHostboolean

Whether the SSH host is validated using the provided fingerprints.

Example
true
knownHostsArray<string>

A list of accepted public key fingerprints. One of these fingerprints must match the fingerprint of the public key the SSH host provides.

Example
[
  "MD5:e0:3a:34:1c:68:ed:c6:bc:7c:ca:a8:67:c7:45:2b:19"
]
tagsArray<string>

The tags of the connection

Parameters

connectionIdstringrequiredpath

The ID of the connection

Response

204No Content

The connection was successfully updated.

400Bad RequestAdvancedError

The request could not be completed. Possible reasons:

  • the connectionId must be an URI,
  • the ID was wrongly set in the request body,
  • the JSON of the connection to be created is invalid.
Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

401UnauthorizedAdvancedError

The request could not be completed due to missing authentication.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

403ForbiddenAdvancedError

The request could not be completed due to invalid authentication.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

404Not FoundAdvancedError

The request could not be completed. The connection with ID connectionId was not found.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

Authorization

DevOpsBasichttp (basic)

Eclipse Ditto devops user (devops) + password (foobar)

DevOpsBearerhttp (bearer)

A JSON Web Token issued by a supported OAuth 2.0 Identity Provider for the Eclipse Ditto devops user.

Docs by Sourcey
↑↓ navigate↵ selectesc close