### Install Docker on Debian/Ubuntu

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2020-04-16-connecting-to-ttn-via-mqtt.md

Installs Docker, starts the service, and adds the current user to the 'docker' group. Remember to log out and back in after running these commands.

```shell
sudo apt install docker.io
sudo service docker start
sudo usermod -a -G docker <your-username>
```

--------------------------------

### Serve Jekyll Documentation Locally on Unix

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/README.md

Navigates to the resources directory, installs bundle dependencies, and starts the Jekyll local server. The server will be available at http://localhost:4000.

```bash
cd src/main/resources
bundle install
bundle exec jekyll serve --verbose --unpublished
```

--------------------------------

### Search Things Scenario Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2023-10-09-ditto-benchmark.md

Example of an HTTP GET request to search for things using a filter. This is used in the 'search things' benchmark scenario.

```bash
${DITTO_BASE_URI}/search/things?filter=eq(thingId, 'org.eclipse.ditto:test-thing-1')
```

--------------------------------

### Start Minikube

Source: https://github.com/eclipse-ditto/ditto/blob/master/deployment/kubernetes/minikube/README.md

Starts the Minikube virtual machine. Use `minikube status` to verify it is running.

```bash
minikube start 

# verify minikube is started
minikube status
```

--------------------------------

### Read Things Scenario Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2023-10-09-ditto-benchmark.md

Example of an HTTP GET request to read a specific thing by its ID. This is used in the 'read things' benchmark scenario.

```bash
${DITTO_BASE_URI}/things/org.eclipse.ditto:test-thing-1
```

--------------------------------

### Install Swagger CLI

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/openapi/README.md

Install the swagger-cli tool by navigating to the sources directory and running npm install.

```bash
$ cd sources && npm install
```

--------------------------------

### Start Swagger UI

Source: https://github.com/eclipse-ditto/ditto/blob/master/deployment/kubernetes/README.md

Apply the Swagger UI deployment configuration to start the Swagger UI service.

```bash
kubectl apply -f deployment/kubernetes/deploymentFiles/swagger/swagger.yaml
```

--------------------------------

### Install Jekyll and Dependencies on Unix

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/README.md

Installs necessary build tools, Ruby development headers, libcurl, zlib, Jekyll, Jekyll-sitemap, and html-proofer. Use the http_proxy parameter if behind a proxy. If html-proofer installation fails, install zlib1g-dev.

```bash
sudo apt-get install build-essential ruby-dev libcurl3 zlib1g-dev
sudo gem install [--http-proxy http://localhost:3128] jekyll
sudo gem install [--http-proxy http://localhost:3128] jekyll-sitemap
sudo gem install [--http-proxy http://localhost:3128] html-proofer
```

```bash
sudo apt install zlib1g-dev
```

--------------------------------

### Install Docker Compose

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2020-04-16-connecting-to-ttn-via-mqtt.md

Downloads and installs the Docker Compose binary. Ensure you have curl installed.

```shell
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

--------------------------------

### Start Reverse Proxy (nginx)

Source: https://github.com/eclipse-ditto/ditto/blob/master/deployment/kubernetes/README.md

Apply the nginx deployment configuration to start the nginx reverse proxy.

```bash
kubectl apply -f deployment/kubernetes/deploymentFiles/nginx/nginx.yaml
```

--------------------------------

### Install k3s

Source: https://github.com/eclipse-ditto/ditto/blob/master/deployment/kubernetes/k3s/README.md

Run this command to install k3s on your system. Ensure port 30080 is available.

```bash
curl -sfL https://get.k3s.io | sh -
```

--------------------------------

### Retrieve Resource Command Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/protocol/examples/policies/generated/commands/query/retrieveresource.md

This example shows the structure of a command to retrieve a resource.

```APIDOC
## RetrieveResource

### Description
This command retrieves a specific resource associated with a thing.

### Method
POST

### Endpoint
/policies/{policyId}/commands/retrieve

### Request Body
- **topic** (string) - Required - The MQTT topic to which the command is sent.
- **headers** (object) - Required - Contains metadata for the command.
  - **correlation-id** (string) - Required - A unique identifier for the command.
- **path** (string) - Required - The path to the resource to be retrieved. It follows the format `entries/{label}/resources/{thingId}:{resourcePath}`.

### Request Example
```json
{
  "topic": "org.eclipse.ditto/the_policy_id/policies/commands/retrieve",
  "headers": {
    "correlation-id": "<command-correlation-id>"
  },
  "path": "/entries/the_label/resources/thing:/the_resource_path"
}
```

### Response
#### Success Response (200)
- **response** (object) - Contains the retrieved resource data.
  - **body** (string) - The content of the resource.
  - **headers** (object) - Headers associated with the resource.

#### Response Example
```json
{
  "response": {
    "body": "{\"some\": \"resource\", \"data\": \"here\"}",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}
```
```

--------------------------------

### Example Created Thing

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2023-10-09-ditto-benchmark.md

An example of a thing created with the specified template, showing its structure and initial properties.

```json
{
    "thingId": "org.eclipse.ditto:test-thing-1",
    "policyId": "org.eclipse.ditto:test-thing-1",
    "definition": "org.eclipse.ditto:coffeebrewer:0.1.0",
    "attributes": {
        "location": "test location",
        "model": "Speaking coffee machine"
    },
    "features": {
        "coffee-brewer": {
            "properties": {
                "brewed-coffees": 0
            }
        }
    }
}
```

--------------------------------

### Install JavaScript SDK for Browser

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/client-sdk-javascript.md

Use this command to install the browser-specific package for the JavaScript SDK.

```bash
npm install @eclipse-ditto/ditto-javascript-client-dom
```

--------------------------------

### Install JavaScript SDK for Node.js

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/client-sdk-javascript.md

Use this command to install the Node.js-specific package for the JavaScript SDK.

```bash
npm install @eclipse-ditto/ditto-javascript-client-node
```

--------------------------------

### Install Dependencies and Build

Source: https://github.com/eclipse-ditto/ditto/blob/master/benchmark-tool/README-artillery.md

Install project dependencies and build the TypeScript code. Ensure you are in the 'artillery-test' directory.

```bash
cd artillery-test/
npm install
npm run build
```

--------------------------------

### Example Ditto Environment Configurations

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/user-interface.md

These JSON configurations define different Ditto environments, including API URIs, Ditto versions, and authentication settings for 'main' and 'devops' contexts. Use these as a starting point for your own UI setup.

```json
{
  "local_ditto": {
    "api_uri": "http://localhost:8080",
    "ditto_version": 3,
    "authSettings": {
      "main": {
        "method": "basic",
        "oidc": { "enabled": false },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": "ditto:ditto"
        },
        "bearer": { "enabled": true },
        "pre": { "enabled": false }
      },
      "devops": {
        "method": "basic",
        "oidc": { "enabled": false },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": "devops:foobar"
        },
        "bearer": { "enabled": true }
      },
      "oidc": {}
    }
  },
  "local_ditto_ide": {
    "api_uri": "http://localhost:8080",
    "ditto_version": 3,
    "authSettings": {
      "main": {
        "method": "pre",
        "oidc": { "enabled": false },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": null
        },
        "bearer": { "enabled": true },
        "pre": {
          "enabled": false,
          "defaultDittoPreAuthenticatedUsername": "pre:ditto"
        }
      },
      "devops": {
        "method": "basic",
        "oidc": { "enabled": false },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": "devops:foobar"
        },
        "bearer": { "enabled": true }
      },
      "oidc": {}
    }
  },
  "ditto_sandbox": {
    "api_uri": "https://ditto.eclipseprojects.io",
    "ditto_version": 3,
    "disableConnections": true,
    "disableOperations": true,
    "authSettings": {
      "main": {
        "method": "basic",
        "oidc": {
          "enabled": true,
          "defaultProvider": "fake"
        },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": "ditto:ditto"
        },
        "bearer": { "enabled": true },
        "pre": { "enabled": false }
      },
      "devops": {
        "method": "basic",
        "oidc": { "enabled": false },
        "basic": { "enabled": false },
        "bearer": { "enabled": false }
      },
      "oidc": {}
    }
  },
  "oidc_example": {
    "api_uri": "http://localhost:8080",
    "ditto_version": 3,
    "authSettings": {
      "main": {
        "method": "oidc",
        "oidc": {
          "enabled": true,
          "defaultProvider": "fake",
          "autoSso": true
        },
        "basic": {
          "enabled": false,
          "defaultUsernamePassword": null
        },
        "bearer": { "enabled": true },
        "pre": {
          "enabled": false,
          "defaultDittoPreAuthenticatedUsername": null
        }
      },
      "devops": {
        "method": "oidc",
        "oidc": {
          "enabled": true,
          "defaultProvider": "fake",
          "autoSso": true
        },
        "basic": {
          "enabled": false,
          "defaultUsernamePassword": null
        },
        "bearer": { "enabled": true }
      },
      "oidc": {
        "providers": {
          "fake": {
            "displayName": "Fake IDP to test",
            "extractBearerTokenFrom": "access_token",
            "authority": "http://localhost:9900/fake",
            "client_id": "some-client-id",
            "redirect_uri": "http://localhost:8000",
            "post_logout_redirect_uri": "http://localhost:8000",
            "response_type": "code",
            "scope": "openid"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Encryption Migration Response (Started/Resumed)

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-manage-connections-piggyback.md

Example response when a migration is successfully started or resumed. Indicates the current phase and start time.

```json
{
  "type": "connectivity.responses:migrateEncryption",
  "status": 202,
  "phase": "snapshots",
  "dryRun": false,
  "resumed": true,
  "startedAt": "2026-02-16T10:00:00Z"
}
```

--------------------------------

### CreateThing Command Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/protocol/examples/things/generated/commands/modify/creatething.md

This example demonstrates how to construct a CreateThing command to create a new Thing with specified ID, policy, definition, attributes, and features.

```APIDOC
## CreateThing

Creates a new Thing with ID ``org.eclipse.ditto:fancy-thing_53`` that uses an existing Policy with ID ``org.eclipse.ditto:the_policy_id``.

### Request Example

```json
{
  "topic": "org.eclipse.ditto/fancy-thing/things/twin/commands/create",
  "headers": {
    "correlation-id": "<command-correlation-id>"
  },
  "path": "/",
  "value": {
    "thingId": "org.eclipse.ditto:fancy-thing_53",
    "policyId": "org.eclipse.ditto:the_policy_id",
    "definition": "org.eclipse.ditto:SomeModel:1.0.0",
    "attributes": {
      "location": {
        "latitude": 44.673856,
        "longitude": 8.261719
      }
    },
    "features": {
      "accelerometer": {
        "properties": {
          "x": 3.141,
          "y": 2.718,
          "z": 1,
          "unit": "g"
        },
        "desiredProperties": {
          "x": 4
        }
      }
    }
  }
}
```
```

--------------------------------

### Start Development Server

Source: https://github.com/eclipse-ditto/ditto/blob/master/ui/readme.md

Use this command to start the local development server for the Ditto UI. Browse to the specified URL to view the application.

```bash
npm run start
```

```bash
http://localhost:8000/
```

--------------------------------

### Search Things with GET Request

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-search.md

Use GET requests to search for Things with specified filters, sorting, and pagination. This example finds Things in the 'living-room' and limits results to 5.

```http
GET .../search/things?filter=eq(attributes/location,"living-room")&option=sort(+thingId),limit(0,5)
```

--------------------------------

### Using the Asynchronous Client Creation

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2020-10-08-asynchronous-client-creation.md

This example demonstrates how to use the asynchronous client creation interface. It shows obtaining a disconnected client, attempting to connect, and handling both successful connections and connection failures, including resource cleanup.

```java
final DisconnectedDittoClient disconnectedClient =
    DittoClients.newDisconnectedInstance(messagingProvider);

disconnectedClient.connect()
    .thenAccept(this::startUsingDittoClient)
    .exceptionally(exception -> {
        this.handleConnectionFailure(exception);
        disconnectedClient.destroy();
        return null;
    });
```

--------------------------------

### Filter by RQL: Like and Exists

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/basic-changenotifications.md

Filter events for Things starting with a specific ID and when a particular feature changes. This example targets Things starting with 'myThing' and the 'lamp' feature.

```text
filter=and(like(thingId,"org.eclipse.ditto:myThing*"),exists(features/lamp))
```

--------------------------------

### Select Specific Fields with GET

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-search.md

Retrieve only specific fields in the search response by using the 'fields' parameter. This example returns only 'thingId' and 'attributes/manufacturer'.

```http
GET .../search/things?filter=eq(attributes/location,"living-room")&fields=thingId,attributes/manufacturer
```

--------------------------------

### Start Ditto with Local Snapshot Images

Source: https://github.com/eclipse-ditto/ditto/blob/master/README.md

Starts Ditto using locally built snapshot Docker images. This involves navigating to the deployment directory, copying the environment file, and running Docker Compose.

```bash
cd ../deployment/docker/
# the "dev.env" file contains the SNAPSHOT number of Ditto, copy it to ".env" so that docker compose uses it:
cp dev.env .env
docker-compose up -d
```

--------------------------------

### Build JavaScript SDK from Source

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/client-sdk-javascript.md

Commands to install dependencies, build the project, and run linting and tests for the JavaScript SDK.

```bash
npm install
npm run build
npm run lint
npm test
```

--------------------------------

### Custom Metrics Configuration (HOCON)

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/operating-monitoring.md

Configure custom metrics in the search service using HOCON. This example defines a metric for produced but not installed devices.

```hocon
ditto {
  search {
    operator-metrics {
      enabled = true
      scrape-interval = 15m
      custom-metrics {
        all_produced_and_not_installed_devices {
          scrape-interval = 5m
          namespaces = [
            "org.eclipse.ditto.smokedetectors"
          ]
          filter = "and(exists(attributes/production-date),not(exists(attributes/installation-date)))"
          tags {
            company = "acme-corp"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example Ditto Environment JSON Configuration

Source: https://github.com/eclipse-ditto/ditto/blob/master/ui/readme.md

Provides a sample JSON file demonstrating how to configure a local Ditto environment, including API URI, version, and authentication settings.

```json
{
  "local_ditto": {
    "api_uri": "http://localhost:8080",
    "ditto_version": 3,
    "disablePolicies": false,
    "disableConnections": false,
    "disableOperations": false,
    "authSettings": {
      "main": {
        "method": "basic",
        "oidc": {
          "enabled": false
        },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": "ditto:ditto"
        },
        "bearer": {
          "enabled": true
        },
        "pre": {
          "enabled": false,
          "defaultDittoPreAuthenticatedUsername": null
        }
      },
      "devops": {
        "method": "basic",
        "oidc": {
          "enabled": false
        },
        "basic": {
          "enabled": true,
          "defaultUsernamePassword": "devops:foobar"
        },
        "bearer": {
          "enabled": true
        }
      }
    }
  }
}
```

--------------------------------

### Encryption Migration Response (Already Completed)

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-manage-connections-piggyback.md

Example response when no migration needs to be started or resumed, indicating it's already completed or was never initiated.

```json
{
  "type": "connectivity.responses:migrateEncryption",
  "status": 200,
  "phase": "already_completed",
  "dryRun": false,
  "resumed": true,
  "startedAt": "2026-02-16T10:00:00Z"
}
```

--------------------------------

### Custom Metrics Example Output

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/operating-monitoring.md

The result of a custom metric operation, exposed as a Prometheus gauge. This specific metric counts devices that are produced but not yet installed.

```text
all_produced_and_not_installed_devices{company="acme-corp"} 42.0
```

--------------------------------

### Example Response for All Service Configurations

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/installation-operating.md

This JSON structure represents an example response when retrieving all service configurations, showing details for gateway and connectivity services.

```json
{
  "gateway": {
    "10.0.0.1": {
      "type": "common.responses:retrieveConfig",
      "status": 200,
      "config": {
        "env": {
          "PATH": "/usr/games:/usr/local/games"
        },
        "service": {
          "instance-id": "10.0.0.1",
          "name": "gateway"
        },
        "vm-args": [
          "-Dfile.encoding=UTF-8"
        ]
      }
    }
  },
  "connectivity": {
    "10.0.0.1": {
      "type": "common.responses:retrieveConfig",
      "status": 200,
      "config": {
        "env": {
          "CONNECTIVITY_FLUSH_PENDING_RESPONSES_TIMEOUT": "3d"
        },
        "service": {
          "instance-id": "10.0.0.1",
          "name": "connectivity"
        },
        "vm-args": [
          "-Dditto.connectivity.connection.snapshot.threshold=2"
        ]
      }
    }
  }
}
```

--------------------------------

### Conditional Requests - Optimistic Locking

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-concepts.md

Example demonstrating optimistic locking by using the `ETag` from a previous GET request in the `If-Match` header for a subsequent PUT request.

```APIDOC
## Optimistic locking

First, retrieve the Thing and its ETag:

`GET .../things/{thingId}`:

Response:

`ETag: "rev:2"`

```json
{
  "thingId": "{thingId}",
  "policyId": "{policyId}",
  "definition": "{definition}",
  "attributes": {
    "manufacturer": "ACME crop",
    "otherData": 4711
  }
}
```

Then update with the ETag in `If-Match` to fix the typo without overwriting concurrent changes:

### Method
PUT

### Endpoint
`/things/{thingId}`

### Headers
`If-Match: "rev:2"`

### Request Body
```json
{
  "attributes": {
    "manufacturer": "ACME corp",
    "otherData": 4711
  }
}
```

### Responses
* `204 No Content` -- no one else changed the Thing since your `GET`
* `412 Precondition Failed` -- someone else modified the Thing in the meantime
```

--------------------------------

### Install Ditto with Ingress Only (No Nginx Pod)

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2026-05-13-ingress-controller-agnostic-helm-chart.md

For production setups that do not require the landing page. This disables the nginx pod and the UI ingress's root path.

```bash
helm install ditto ditto/ditto \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=ditto.example.com \
  --set nginx.enabled=false
```

--------------------------------

### Example: Return the first ten items using RQL limit

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/basic-search.md

Demonstrates how to fetch the initial set of items using the deprecated RQL `limit` option.

```text
limit(0,10)
```

--------------------------------

### Install Ditto with Standalone Nginx Pod

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2026-05-13-ingress-controller-agnostic-helm-chart.md

Use this command for local and development setups where no external ingress controller is needed. Access Ditto via port-forward.

```bash
helm install ditto ditto/ditto
kubectl port-forward svc/ditto-nginx 8080:8080
```

--------------------------------

### Basic MQTT Connection Configuration

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-mqtt.md

Example of a standard MQTT connection configuration, including URI, sources, and targets.

```json
{
  "id": "mqtt-example-connection-123",
  "connectionType": "mqtt",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "tcp://test.mosquitto.org:1883",
  "sources": [{
    "addresses": ["eclipse-ditto-sandbox/#"],
    "authorizationContext": ["ditto:inbound-auth-subject"],
    "qos": 0
  }],
  "targets": [{
    "address": "eclipse-ditto-sandbox/{%raw%}{{ thing:id }}{%endraw%}",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"],
    "qos": 0
  }]
}
```

--------------------------------

### Retrieve and Create Policies

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/client-sdk-java.md

Demonstrates how to retrieve an existing policy by its ID and how to build and create a new policy with specific permissions for different resource types.

```java
// Read
Policy policy = client.policies()
    .retrieve(PolicyId.of("org.eclipse.ditto:new-policy"))
    .toCompletableFuture().get();

// Create
Policy newPolicy = Policy.newBuilder(
        PolicyId.of("org.eclipse.ditto:new-policy"))
    .forLabel("DEFAULT")
    .setSubject(Subject.newInstance(
        SubjectIssuer.newInstance("nginx"), "ditto"))
    .setGrantedPermissions(
        PoliciesResourceType.policyResource("/"),
        "READ", "WRITE")
    .setGrantedPermissions(
        PoliciesResourceType.thingResource("/"),
        "READ", "WRITE")
    .build();

client.policies().create(newPolicy)
    .toCompletableFuture().get();
```

--------------------------------

### Restrict Search to Namespaces with GET

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-search.md

Filter search results to specific namespaces by providing a comma-separated list in the 'namespaces' parameter. This example searches within 'org.eclipse.ditto' and 'foo.bar'.

```http
GET .../search/things?filter=eq(attributes/location,"living-room")&namespaces=org.eclipse.ditto,foo.bar
```

--------------------------------

### Filter by RQL: Encoded Characters

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/basic-changenotifications.md

When filtering by string values containing special characters like '&', ensure they are URL-encoded. This example filters for 'manufacturer' starting with 'ACME & Sons'.

```text
filter=like(attributes/manufacturer,"ACME %26 Sons*")
```

--------------------------------

### AMQP 1.0 Source Configuration Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp10.md

Example of a common source configuration for AMQP 1.0, specifying addresses and authorization context.

```json
{
  "addresses": ["telemetry/FOO"],
  "authorizationContext": ["ditto:inbound-auth-subject"]
}
```

--------------------------------

### Example AMQP 1.0 Connection JSON

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp10.md

A complete example of an AMQP 1.0 connection configuration in JSON format, including URI, sources, and targets.

```json
{
  "id": "hono-example-connection-123",
  "connectionType": "amqp-10",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "amqps://user:password@hono.eclipse.org:5671",
  "sources": [{
    "addresses": ["telemetry/FOO"],
    "authorizationContext": ["ditto:inbound-auth-subject"]
  }],
  "targets": [{
    "address": "events/twin",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"]
  }]
}
```

--------------------------------

### Direct HTTP Invocation Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-protocol-bindings-cloudevents.md

Demonstrates a direct HTTP POST request to the Cloud Events endpoint. Ensure the `ce-dataschema` starts with `ditto:` and the payload is Ditto Protocol JSON.

```http
POST /api/2/cloudevents HTTP/1.1
ce-specversion: 1.0
ce-type: my.ditto.event
ce-time: 2020-11-24T14:35:00Z
ce-id: f7b197fe-2e59-11eb-a8f4-d45d6455d2cc
ce-source: /my/source
ce-dataschema: ditto:some-schema
Content-Type: application/json; charset=utf-8

{
    ... Ditto Protocol JSON ...
}
```

--------------------------------

### Kafka Source Configuration Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-kafka2.md

Example of a Kafka source configuration, including quality of service and reply target settings. Ensure 'bootstrapServers' is set in 'specificConfig'.

```json
{
  "addresses": ["theTopic"],
  "consumerCount": 1,
  "qos": 1,
  "authorizationContext": ["ditto:inbound-auth-subject"],
  "enforcement": {
    "input": "{{ header:device_id }}",
    "filters": ["{{ entity:id }}"]
  },
  "headerMapping": {},
  "payloadMapping": ["Ditto"],
  "replyTarget": {
    "enabled": true,
    "address": "theReplyTopic",
    "headerMapping": {},
    "expectedResponseTypes": ["response", "error", "nack"]
  },
  "acknowledgementRequests": {
    "includes": []
  },
  "declaredAcks": []
}
```

--------------------------------

### Policy Setup for Provider Microservice

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/advanced-data-by-pass.md

Configure policies to restrict access to the provider microservice. This example grants read access to incoming messages and write access to outgoing messages on a specific topic.

```json
{
  "subjects": {},
  "resources": {
    "message:/": {
      "grant": [],
      "revoke": ["READ", "WRITE"]
    },
    "message:/inbox/messages/services/history": {
      "grant": ["READ"],
      "revoke": []
    },
    "message:/outbox/messages/services/history": {
      "grant": ["WRITE"],
      "revoke": []
    }
  }
}
```

--------------------------------

### Complete Thing Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/basic-thing.md

Provides a comprehensive example of a Thing's JSON structure, including ID, policy, definition, attributes, and features.

```json
{
  "thingId": "the.namespace:theName",
  "policyId": "the.namespace:thePolicyName",
  "definition": "org.eclipse.ditto:HeatingDevice:2.1.0",
  "attributes": {
    "someAttr": 32,
    "manufacturer": "ACME corp"
  },
  "features": {
    "heating-no1": {
      "properties": {
        "connected": true,
        "complexProperty": {
          "street": "my street",
          "house no": 42
        }
      },
      "desiredProperties": {
        "connected": false
      }
    },
    "switchable": {
      "definition": [ "org.eclipse.ditto:Switcher:1.0.0" ],
      "properties": {
        "on": true,
        "lastToggled": "2017-11-15T18:21Z"
      }
    }
  }
}
```

--------------------------------

### Retrieve Historical Events via SSE

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/basic-history.md

This example shows how to fetch historical events for a specific thing using Server-Sent Events (SSE). You can specify a range of historical revisions or timestamps and select specific fields to retrieve. The `_context` field can be included to get historical headers.

```APIDOC
## Retrieve Historical Events via SSE

### Description
Fetch historical events for a specific thing using Server-Sent Events (SSE). You can specify a range of historical revisions or timestamps and select specific fields to retrieve. The `_context` field can be included to get historical headers.

### Method
GET

### Endpoint
`/api/2/things/{thingId}?from-historical-revision={revision}&fields={fields}`

### Query Parameters
- **from-historical-revision** (integer) - Required - The starting revision number for historical data.
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.
- **from-historical-timestamp** (string) - Optional - The starting timestamp for historical data (ISO 8601 format).
- **to-historical-timestamp** (string) - Optional - The ending timestamp for historical data (ISO 8601 format).

### Request Example
```bash
curl --http2 -u ditto:ditto -H 'Accept:text/event-stream' -N \
  http://localhost:8080/api/2/things/org.eclipse.ditto:thing-2?from-historical-revision=0&fields=thingId,attributes,features,_revision,_modified,_context
```

### Response Example
(SSE stream of historical events)
```

--------------------------------

### API Request with Live Channel Condition

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2021-12-22-live-channel-condition.md

This example shows an HTTP GET request to retrieve a device's temperature property. The 'live-channel-condition' parameter uses the 'readyUntil' timestamp from the 'ConnectionStatus' feature to ensure data is fetched only when the device is considered connected. A 'timeout' and 'live-channel-timeout-strategy' are also specified.

```http
GET /api/2/things/my.namespace:my-connection-aware-device-1/features/temperature/properties/value
  ?live-channel-condition=gt(features/ConnectionStatus/properties/status/readyUntil,time:now)
  &timeout=10s
  &live-channel-timeout-strategy=use-twin
```

--------------------------------

### Create Subscription Command

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/protocol/examples/search/protocol-examples-search.md

Example of how to create a new subscription using the Ditto protocol.

```json
{
  "headers": {
    "correlationId": "my-correlation-id",
    "messageId": "my-message-id"
  },
  "payload": {
    "filter": {
      "//": "This is a comment, it will be ignored.",
      "thingId": {
        "namespace": "my_namespace",
        "name": "my_thing_id"
      },
      "attribute": "value"
    },
    "//": "This is a comment, it will be ignored.",
    "url": "http://my-callback-url.com/my-handler",
    "accepts": "application/json"
  }
}
```

--------------------------------

### Setup Hono Tenant

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2018-12-05-example-command-and-control.md

Use this command to set up a tenant in Eclipse Hono. Ensure you have the correct API endpoint.

```bash
# setup a tenant
$ curl -X POST -i -H 'Content-Type: application/json' -d '{"tenant-id": "org.eclipse.ditto"}' https://hono.eclipse.io:28080/tenant
```

--------------------------------

### Count Things with GET

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-search.md

Get the number of Things matching a filter using a GET request.

```APIDOC
## GET /api/2/search/things/count

### Description
Retrieves the count of Things that match the specified filter.

### Method
GET

### Endpoint
/api/2/search/things/count

### Parameters
#### Query Parameters
- **filter** (string) - Required - RQL filter expression to select Things.

### Request Example
```
GET .../search/things/count?filter=eq(attributes/location,"living-room")
```

### Response
#### Success Response (200)
- **body** (integer) - The number of Things matching the filter.
```

--------------------------------

### Example AMQP 0.9.1 Connection Configuration

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp091.md

A complete example of an AMQP 0.9.1 connection configuration in Ditto, including sources and targets.

```json
{
  "id": "rabbit-example-connection-123",
  "connectionType": "amqp-091",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "amqp://user:password@localhost:5672/vhost",
  "sources": [{
    "addresses": ["queueName"],
    "authorizationContext": ["ditto:inbound-auth-subject"]
  }],
  "targets": [{
    "address": "exchangeName/routingKey",
    "topics": [
      "_/ப்புகளை/things/twin/events",
      "_/ப்புகளை/things/live/messages"
    ],
    "authorizationContext": ["ditto:outbound-auth-subject"]
  }]
}
```

--------------------------------

### Example Thing JSON

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/_posts/2021-09-23-conditional-requests.md

This JSON represents an example thing with attributes and features used in conditional request examples.

```json
{
  "thingId": "org.eclipse.ditto:coffeebrewer",
  "policyId": "org.eclipse.ditto:coffeebrewer-policy",
  "definition": "org.eclipse.ditto:coffeebrewer:0.1.0",
  "attributes": {
    "manufacturer": "ACME demo corp.",
    "location": "Wonderland",
    "serialno": "42",
    "model": "Speaking coffee machine"
  },
  "features": {
    "coffee-brewer": {
      "definition": ["org.eclipse.ditto:coffeebrewer:0.1.0"],
      "properties": {
        "brewed-coffees": 0
      }
    },
    "water-tank": {
      "properties": {
        "configuration": {
          "smartMode": true,
          "brewingTemp": 87,
          "tempToHold": 44.5,
          "timeoutSeconds": 6000
        },
        "status": {
          "waterAmount": 731,
          "temperature": 44.2,
          "lastModified": "2021-09-23T07:01:56Z"
        }
      }
    }
  }
}
```

--------------------------------

### Count Things with GET Request

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/httpapi-search.md

Get the total number of Things that match a given filter using the '/count' endpoint with a GET request.

```http
GET .../search/things/count?filter=eq(attributes/location,"living-room")
```

--------------------------------

### Get Connection Status via HTTP GET

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-manage-connections.md

Retrieve the current status of a connection, indicating if it is enabled/disabled and successfully established, by sending an HTTP GET request to /api/2/connections/{connectionId}/status.

```http
GET /api/2/connections/{connectionId}/status
```

--------------------------------

### Example MQTT 5 Connection JSON

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-mqtt5.md

A basic example of an MQTT 5 connection configuration, including URI, sources, and targets. This configuration uses standard MQTT connection details.

```json
{
  "id": "mqtt5-example-connection-12",
  "connectionType": "mqtt-5",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "tcp://test.mosquitto.org:1883",
  "sources": [{
    "addresses": ["eclipse-ditto-sandbox/#"],
    "authorizationContext": ["ditto:inbound-auth-subject"],
    "qos": 0
  }],
  "targets": [{
    "address": "eclipse-ditto-sandbox/{%raw%}{{ thing:id }}{%endraw%}",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"],
    "qos": 0
  }]
}
```

--------------------------------

### Target Configuration with Placeholder

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-http.md

Example of a target configuration for an HTTP connection, demonstrating the use of a placeholder in the path for dynamic entity IDs.

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

--------------------------------

### ConnectionStatus Feature Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-mapping.md

An example of the resulting ConnectionStatus feature structure after transformation.

```json
{
  "thingId": "eclipse:ditto",
  "features": {
    "ConnectionStatus": {
      "definition": [ "org.eclipse.ditto:ConnectionStatus:1.0.0" ],
      "properties": {
        "status": {
          "readySince": "2019-10-29T14:16:18Z",
          "readyUntil": "2019-10-29T14:21:18Z"
        }
      }
    }
  }
}
```

--------------------------------

### RetrievePolicyIdResponse Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/protocol/examples/things/generated/commands/query/retrievepolicyidresponse.md

This is an example of the JSON response received when a policy ID is successfully retrieved.

```APIDOC
## RetrievePolicyIdResponse

### Description
This is the response structure for a command that retrieves a policy ID.

### Response Example
```json
{
  "topic": "org.eclipse.ditto/fancy-thing/things/twin/commands/retrieve",
  "headers": {
    "correlation-id": "<preserved-command-correlation-id>"
  },
  "path": "/policyId",
  "value": "org.eclipse.ditto:the_policy_id",
  "status": 200
}
```

### Response Fields
- **topic** (string) - The topic where the response is published.
- **headers** (object) - Headers of the response, including correlation ID.
  - **correlation-id** (string) - The correlation ID of the original command.
- **path** (string) - The path related to the retrieved policy ID.
- **value** (string) - The actual policy ID.
- **status** (integer) - The HTTP status code of the response, typically 200 for success.
```

--------------------------------

### RetrieveResourcesResponse Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/protocol/examples/policies/generated/commands/query/retrieveresourcesresponse.md

An example of the JSON response received after a successful resource retrieval command.

```APIDOC
## RetrieveResourcesResponse

This is the structure of the response when retrieving resources.

### Response Body Example

```json
{
  "topic": "org.eclipse.ditto/the_policy_id/policies/commands/retrieve",
  "headers": {
    "correlation-id": "<preserved-command-correlation-id>"
  },
  "path": "/entries/the_label/resources",
  "value": {
    "thing:/the_resource_path": {
      "grant": [
        "READ",
        "WRITE"
      ],
      "revoke": []
    }
  },
  "status": 200
}
```

### Response Fields

- **topic** (string) - The MQTT topic where the response is published.
- **headers** (object) - Contains metadata about the response, including correlation ID.
  - **correlation-id** (string) - The correlation ID preserved from the original command.
- **path** (string) - The path indicating the context of the resource retrieval.
- **value** (object) - An object containing the retrieved resources and their associated permissions.
  - **thing:/the_resource_path** (object) - Represents a specific resource path.
    - **grant** (array of strings) - A list of permissions granted for this resource.
    - **revoke** (array of strings) - A list of permissions to be revoked for this resource.
- **status** (integer) - The HTTP status code of the response, indicating success (e.g., 200).
```

--------------------------------

### Build Bundled API Docs

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/openapi/README.md

Build the bundled API documentation by navigating to the sources directory and running the npm build script.

```bash
// go to sources
$ cd sources

// run build
$ npm run build
```

--------------------------------

### Example: Return ten items with a cursor

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/basic-search.md

This example demonstrates how to retrieve a specific number of items using cursor-based pagination.

```text
option=size(10),cursor(<cursor-from-previous-result>)
```

--------------------------------

### AMQP 1.0 Target Configuration Example

Source: https://github.com/eclipse-ditto/ditto/blob/master/documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp10.md

Example of a common target configuration for AMQP 1.0, specifying address, topics, and authorization context.

```json
{
  "address": "events/twin",
  "topics": [
    "_/_/things/twin/events",
    "_/_/things/live/messages"
  ],
  "authorizationContext": ["ditto:outbound-auth-subject"]
}
```