HTTP 1.1 protocol binding

You use the HTTP 1.1 binding to push data from Ditto to external HTTP endpoints using GET, POST, PUT, or PATCH requests.

Overview

The HTTP 1.1 protocol binding lets you perform HTTP requests to external endpoints via targets. This is useful for forwarding events, sending messages, or integrating with REST APIs.

Connection URI format

http://user:password@hostname:80

Use https:// for TLS-secured connections.

Source configuration

HTTP connections do not support sources.

Target configuration

The common target configuration applies. The target address combines an HTTP verb and path:

<http_verb>:<http_path>

Supported HTTP verbs: GET, POST, PUT, PATCH.

The <http_path> is appended to the connection uri. It can include query parameters and placeholders.

{
  "address": "PUT:/api/2/some-entity/{{ thing:id }}",
  "topics": [
    "_/_/things/twin/events",
    "_/_/things/live/messages"
  ],
  "authorizationContext": ["ditto:outbound-auth-subject"],
  "headerMapping": {
    "content-type": "application/json"
  }
}

Target header mapping

HTTP connections support full header mapping. These special headers control the HTTP request directly:

Target acknowledgement handling

You have two options for acknowledging messages sent to HTTP endpoints:

Explicit Ditto Protocol acknowledgement

If the HTTP endpoint responds with a Ditto Protocol Acknowledgement and sets Content-Type: application/vnd.eclipse.ditto+json, Ditto treats the response as a custom acknowledgement. This only works if no issued acknowledgement label is configured.

Implicit acknowledgement from HTTP response

When an issued acknowledgement label is configured, the HTTP response is automatically mapped to an acknowledgement:

• Acknowledgement.status – the HTTP response status code
• Acknowledgement.headers – the HTTP response headers
• Acknowledgement.value – the HTTP response body (inlined as JSON if application/json, otherwise as a string)

Responding to live messages

For live messages published via HTTP targets, you can respond in two ways:

1. Explicit – respond with a Ditto Protocol Message Response with Content-Type: application/vnd.eclipse.ditto+json. The correlation-id, thing-id, and potentially feature-id of the response must match the original message.
2. Implicit – configure the issued acknowledgement label live-response, and the HTTP response is automatically converted to a message response when the response is not a Ditto Protocol message (i.e., not application/vnd.eclipse.ditto+json). The HTTP response is mapped as follows:
   • Message.headers – the HTTP response headers
   • Message.status – the HTTP response status code
   • Message.value – the HTTP response body (inlined as JSON if application/json, otherwise as a string)

Specific configuration options

Example connection JSON

{
  "id": "http-example-connection-123",
  "connectionType": "http-push",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "http://user:password@localhost:80",
  "specificConfig": {
    "parallelism": "2"
  },
  "sources": [],
  "targets": [{
    "address": "PUT:/api/2/some-entity/{{ thing:id }}",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"],
    "headerMapping": {
      "content-type": "{{ header:content-type }}",
      "api-key": "this-is-a-secret-api-key"
    }
  }]
}

Client-certificate authentication

Ditto supports certificate-based authentication for HTTP connections. See TLS certificates for setup instructions.

{
  "id": "http-example-connection-123",
  "connectionType": "http-push",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "https://localhost:443",
  "validateCertificates": true,
  "ca": "-----BEGIN CERTIFICATE-----\n<server certificate>\n-----END CERTIFICATE-----",
  "credentials": {
    "type": "client-cert",
    "cert": "-----BEGIN CERTIFICATE-----\n<client certificate>\n-----END CERTIFICATE-----",
    "key": "-----BEGIN PRIVATE KEY-----\n<client private key>\n-----END PRIVATE KEY-----"
  },
  "specificConfig": {
    "parallelism": "2"
  },
  "sources": [],
  "targets": [{
    "address": "PUT:/api/2/some-entity/{{ thing:id }}",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"],
    "headerMapping": {
      "content-type": "{{ header:content-type }}"
    }
  }]
}

HMAC request signing

Ditto supports HMAC request signing for HTTP push connections. See HMAC request signing for details.

OAuth2 authentication

HTTP connections support OAuth2 for obtaining bearer tokens. Each request includes a token issued by the configured token endpoint. Ditto obtains a new token before the old one expires.

You can configure max-clock-skew and HTTPS enforcement in connectivity-extension.conf:

ditto {
  connectivity {
    connection {
      http-push {
        oauth2 {
          max-clock-skew = 60s
          max-clock-skew = ${?CONNECTIVITY_HTTP_OAUTH2_MAX_CLOCK_SKEW}

          enforce-https = true
          enforce-https = ${?CONNECTIVITY_HTTP_OAUTH2_ENFORCE_HTTPS}
        }
      }
    }
  }
}

OAuth2 client credentials flow

Authenticate via RFC-6749 Section 4.4:

{
  "credentials": {
    "type": "oauth-client-credentials",
    "tokenEndpoint": "https://auth.example.com/oauth2/token",
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "requestedScopes": "scope-1 scope-2"
  }
}

OAuth2 password flow

Authenticate via RFC-6749 Section 4.3. Optionally set clientSecret to include a client secret in access token requests, or leave it out if the client is public and does not have a secret:

{
  "credentials": {
    "type": "oauth-password",
    "tokenEndpoint": "https://auth.example.com/oauth2/token",
    "clientId": "my-public-client-id",
    "requestedScopes": "scope-1 scope-2",
    "username": "my-username",
    "password": "my-password"
  }
}

Further reading

• Connections overview – connection model and configuration
• Payload mapping – transform message payloads
• Header mapping – map external headers
• HMAC signing – HMAC-based authentication
• TLS certificates – secure connections with TLS