CloudEvents

Processes a CloudEvent sent in Ditto Protocol

POST

https://ditto.eclipseprojects.io/api/2/cloudevents

Provides an endpoint accepting CloudEvents via its HTTP protocol binding in Ditto Protocol JSON.

The endpoint can also directly be configured as a Knative eventing destination.

Find more documentation on that here.

Processes a CloudEvent sent in Ditto Protocol

curl -X POST 'https://ditto.eclipseprojects.io/api/2/cloudevents' \
  -H 'ce-specversion: 1.0' \
  -H 'ce-type: com.example.someevent' \
  -H 'ce-source: /mycontext' \
  -H 'ce-id: 1234-1234-1234' \
  -H 'ce-time: 2020-12-31T23:59:59Z' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/vnd.eclipse.ditto+json' \
  --data-raw '{
  "topic": "org.eclipse.ditto/thing-1/things/twin/commands/modify",
  "path": "/",
  "value": {
    "attributes": {
      "foo": 42
    }
  }
}'

const body = `{
  "topic": "org.eclipse.ditto/thing-1/things/twin/commands/modify",
  "path": "/",
  "value": {
    "attributes": {
      "foo": 42
    }
  }
}`;

const response = await fetch('https://ditto.eclipseprojects.io/api/2/cloudevents', {
  method: 'POST',
  headers: {
    'ce-specversion': '1.0',
    'ce-type': 'com.example.someevent',
    'ce-source': '/mycontext',
    'ce-id': '1234-1234-1234',
    'ce-time': '2020-12-31T23:59:59Z',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/vnd.eclipse.ditto+json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "topic": "org.eclipse.ditto/thing-1/things/twin/commands/modify",
  "path": "/",
  "value": {
    "attributes": {
      "foo": 42
    }
  }
}'''

response = requests.post(
    'https://ditto.eclipseprojects.io/api/2/cloudevents',
    data=body.encode('utf-8'),
    headers={
        'ce-specversion': '1.0',
        'ce-type': 'com.example.someevent',
        'ce-source': '/mycontext',
        'ce-id': '1234-1234-1234',
        'ce-time': '2020-12-31T23:59:59Z',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/vnd.eclipse.ditto+json',
    },
)
print(response.text)

Request Body

{
  "topic": "org.eclipse.ditto/thing-1/things/twin/commands/modify",
  "path": "/",
  "value": {
    "attributes": {
      "foo": 42
    }
  }
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

Body

application/vnd.eclipse.ditto+json

The Ditto Protocol JSON payload defining which command to process.

topicstringrequired

Contains information about the contents of the payload:

the affected Thing (namespace and Thing ID)
the type of operation (command/event, create/retrieve/modify/delete)

Example

org.eclipse.ditto/thing-1/things/twin/commands/modify

headersobject

Additional headers.

Show child attributes

correlation-idstring

The correlation-id header is used for linking one message with another. It typically links a reply message with its requesting message.

Example

{
  "correlation-id": "1234-4321-1234"
}

pathstringrequired

References the part of a Thing which is affected by this message.

Example

/features/location/properties/longitude

valueobject | string | number | array | boolean

The value field contains the actual payload e.g. a sensor value.

Show child attributes

One of

object

string

number

array

boolean

Parameters

ce-specversionstringrequiredheader

The CloudEvents "specversion".

ce-typestringrequiredheader

The CloudEvents event "type".

ce-sourcestringrequiredheader

The CloudEvents event "source".

ce-idstringrequiredheader

The CloudEvents event "id".

ce-timestring<date-time>requiredheader

The CloudEvents event "time".

ce-dataschemastringheader

The CloudEvents event "dataschema". If provided, this must start with ditto:.

Response

202Accepted

The Ditto Protocol CloudEvent was successfully parsed, the authentication was valid and also reached the persistence.

400Bad RequestAdvancedError

The request could not be completed. Possible reasons:

the CloudEvent could not be parsed as some mandatory CloudEvent headers were missing from the request
the payload was missing from the CloudEvent
the Ditto Protocol JSON message could not be parsed or was missing a required field

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. Possible reasons:

the caller has insufficient permissions.

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. Possible reasons:

the referenced thing does not exist.
the caller has insufficient permissions to perform the contained Ditto Protocol command.

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

408Request TimeoutAdvancedError

The request could not be completed due to timeout.

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

415Unsupported Media TypeAdvancedError

The Content-Type of the request was not supported.

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

OpenIDConnectopenIdConnect

OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.

NginxBasichttp (basic)

Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)

Bearerhttp (bearer)

A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Docs by Sourcey