Eclipse Ditto Client

Eclipse Ditto Project - https://eclipse.dev/ditto/index.html

This repository is the python client generated using Microsoft Kiota (https://github.com/microsoft/kiota-python) and a CLI based client.

Install

uv add ditto-client

Running Ditto

There are 3 modes in which you can run Eclipse Ditto from this repository

Mode 1

A docker compose that has nginx as a reverse proxy and configured to do Basic Authentication.

# to start nginx reverse proxy based setup (that uses Basic Authentication)
uv run poe compose-ba-up

# to stop nginx reverse proxy based setup
uv run poe compose-ba-down

Mode 2

A docker compose that exposes the Eclipse Ditto Gateway at port 8081 and sets ENABLE_PRE_AUTHENTICATION=true

In this mode, the client application directly talks to the gateway and sets the header

# to start with out nginx and pre-auth setup
uv run poe compose-pre-up

# to stop
uv run poe compose-pre-down

Mode 3

A docker compose that exposes the Eclipse Ditto Gateway at port 8081 and sets ENABLE_PRE_AUTHENTICATION=false and requires JWT based authentication

In this mode, the client application first gets the JWT token from the issuer and then pass it to the gateway

Look at assets/ditto/ditto-gateway-jwt.yml to learn about the settings (A mock oauth server is included)

# to start with out nginx and pre-auth setup
uv run poe compose-jwt-up

# to stop
uv run poe compose-jwt-down

Usage - API

Basic Authentication

auth_provider = BasicAuthProvider(user_name=_USERNAME, password=_PASSWORD)

request_adapter = HttpxRequestAdapter(auth_provider)
request_adapter.base_url = "http://host.docker.internal:8080"

ditto_client = DittoClient(request_adapter)

response = await ditto_client.api.two.things.get()

Default setup for Ditto uses Ngix with basic authentication. A custom authentication provider has been included in the library to support it. See BasicAuth Provider.

See examples/basic.py for the full usage

Pre Authentication

auth_provider = PreAuthProvider(auth_subject="ditto:ditto")

request_adapter = HttpxRequestAdapter(auth_provider)
# Note the port is that of gateway
request_adapter.base_url = "http://host.docker.internal:8081"

ditto_client = DittoClient(request_adapter)

response = await ditto_client.api.two.things.get()

A custom authentication provider has been included. See PreAuth Provider.

See examples/pre.py for the full usage

JWT Authentication

auth_provider = JWTAuthProvider(token=<your_token>")

request_adapter = HttpxRequestAdapter(auth_provider)
# Note the port is that of gateway
request_adapter.base_url = "http://host.docker.internal:8081"

ditto_client = DittoClient(request_adapter)

response = await ditto_client.api.two.things.get()

A custom authentication provider has been included. See JWTAuth Provider.

See examples/jwt.py for the full usage

Usage - CLI

The Ditto client includes a comprehensive CLI for interacting with Eclipse Ditto services. The CLI provides the following commands:

 Usage: ditto-client [OPTIONS] COMMAND [ARGS]...

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --loglevel            -l      TEXT                  Set the logging level (debug, info, warning, error, critical) [default: warning]                                        │
│ --base-url                    TEXT                  Base URL for the Ditto API (can also be set via DITTO_BASE_URL environment variable) [env var: DITTO_BASE_URL]          │
│                                                     [default: http://host.docker.internal:8080]                                                                             │
│ --auth-type                   [basic|pre-auth|jwt]  Set the authentication type (basic, pre-auth) [default: basic]                                                          │
│ --username                    TEXT                  Username for basic authentication (can also be set via DITTO_USERNAME environment variable) [env var: DITTO_USERNAME]   │
│ --password                    TEXT                  Password for basic authentication (can also be set via DITTO_PASSWORD environment variable) [env var: DITTO_PASSWORD]   │
│ --preauth-subject             TEXT                  Auth subject for pre-authentication (can also be set via DITTO_PREAUTH_SUBJECT environment variable)                    │
│                                                     [env var: DITTO_PREAUTH_SUBJECT]                                                                                        │
│ --jwt-token                   TEXT                  JWT token for authentication (can also be set via DITTO_JWT_TOKEN environment variable) [env var: DITTO_JWT_TOKEN]      │
│ --table                                             Output results as a rich table instead of JSON                                                                          │
│ --install-completion                                Install completion for the current shell.                                                                               │
│ --show-completion                                   Show completion for the current shell, to copy it or customize the installation.                                        │
│ --help                                              Show this message and exit.                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ whoami       Get current user information.                                                                                                                                  │
│ policy       Policy management                                                                                                                                              │
│ thing        Thing management                                                                                                                                               │
│ search       Thing search                                                                                                                                                   │
│ permission   Permission check                                                                                                                                               │
│ devops       DevOps                                                                                                                                                         │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Global Configuration

You can pass various secrets on the command line and/or use the .env file.

See .env.example for the entries

Policy Management

Create a new policy.

# Create a new policy
ditto-client policy create "my.sensors:sensor-policy" examples/cli-examples/policy.json

Retrieve a specific policy by ID.

# Get a policy
ditto-client policy get "my.sensors:sensor-policy"

List policy entries.

# List all policy entries
ditto-client policy entries "my.sensors:sensor-policy"

Delete policy.

# Delete a policy
ditto-client policy delete "my.sensors:sensor-policy"

Things Management

Create a new thing.

# Make sure to create the policy (my.sensors:sensor-policy) See above example
# Create a new thing
ditto-client thing create "my.sensors:sensor-001" examples/cli-examples/thing-humidity.json

List all things with optional filtering.

# List all things
ditto-client thing list

# List things with specific fields
ditto-client thing list --fields "thingId,attributes"

# List specific things by ID
ditto-client thing list --ids "my.sensors:sensor-001"

Retrieve a specific thing by ID.

# Get a specific thing
ditto-client thing get "my.sensors:sensor-001"

# Get a specific revision of a thing
ditto-client thing get "my.sensors:sensor-001" --revision 1

Update a thing using JSON file.

# Update a thing
ditto-client thing update "my.sensors:sensor-001" examples/cli-examples/thing-humidity.json

Compare current thing with historical revision.

# Compare current state with revision 1
ditto-client thing diff "my.sensors:sensor-001" 1

Delete a thing.

# Delete a thing
ditto-client thing delete "my.sensors:sensor-001"

Search Operations

Refer below documentation to understand RQL syntax: https://eclipse.dev/ditto/1.5/basic-rql.html

Search for things using RQL (Resource Query Language).

# Search all things
ditto-client search query

# Search with filter
ditto-client search query --filter 'eq(attributes/location,"Kitchen")'

# Search with size limit and sorting
ditto-client search query --option "size(3),sort(+thingId)"

# Search in specific namespaces
ditto-client search query --namespaces "my.sensors"

Count things matching search criteria.

# Count all things
ditto-client search count

# Count things with filter
ditto-client search count --filter 'eq(attributes/location,"Kitchen")'

Connection Management (DevOps)

Create a new connection.

# Create a connection
ditto-client devops connection create "new-connection" examples/cli-examples/connection.json

List all connections.

# List all connections
ditto-client devops connection list

# List with specific fields
ditto-client devops connection list --fields "id,connectionStatus"

Retrieve a specific connection by ID.

# Get a connection
ditto-client devops connection get "new-connection"

# Get with specific fields
ditto-client devops connection get "new-connection" --fields "id,status"

Delete a connection.

# Delete a connection
ditto-client devops connection delete "new-connection"

Configuration Management (DevOps)

Retrieve service configuration.

# Get all configuration
ditto-client devops config get

Logging Management (DevOps)

Retrieve logging configuration.

# Get logging configuration
ditto-client devops logging get

# Get module-specific config
ditto-client devops logging get --module-name "gateway"

Update logging configuration.

# Update logging configuration
ditto-client devops logging update examples/cli-examples/logging.json

Permission Management (DevOps)

Check permissions on specified resources.

# Check permissions
ditto-client permission check examples/cli-examples/permission.json

Get current user information.

# Get current user info
ditto-client whoami