# Processes a CloudEvent sent in Ditto Protocol

`POST /api/2/cloudevents`

Provides an endpoint accepting [CloudEvents via its HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md)
in [Ditto Protocol JSON](https://www.eclipse.dev/ditto/protocol-specification.html).

The endpoint can also directly be configured as a [Knative eventing](https://knative.dev/docs/eventing/) destination.

Find more documentation on that [here](https://www.eclipse.dev/ditto/httpapi-protocol-bindings-cloudevents.html).

Authentication (security requirement alternatives):

```json
[
  {
    "OpenIDConnect": []
  },
  {
    "NginxBasic": []
  },
  {
    "Bearer": []
  }
]
```

- OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
- NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
- Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Parameters:

- `ce-specversion` (header, string, required) - The CloudEvents "specversion".
  Type: string
  
  Example:
  
  ```json
  "1.0"
  ```

- `ce-type` (header, string, required) - The CloudEvents event "type".
  Type: string
  
  Example:
  
  ```json
  "com.example.someevent"
  ```

- `ce-source` (header, string, required) - The CloudEvents event "source".
  Type: string
  
  Example:
  
  ```json
  "/mycontext"
  ```

- `ce-id` (header, string, required) - The CloudEvents event "id".
  Type: string
  
  Example:
  
  ```json
  "1234-1234-1234"
  ```

- `ce-time` (header, string, date-time, required) - The CloudEvents event "time".
  Type: string, date-time
  
  Example:
  
  ```json
  "2020-12-31T23:59:59Z"
  ```

- `ce-dataschema` (header, string, optional) - The CloudEvents event "dataschema". If provided, this must start with `ditto:`.
  Type: string

Request body: application/vnd.eclipse.ditto+json

The [Ditto Protocol JSON](https://www.eclipse.dev/ditto/protocol-specification.html) payload defining which
command to process.

Type: object

- `topic` (required)
  Type: string
  
  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:
  
  ```json
  "org.eclipse.ditto/thing-1/things/twin/commands/modify"
  ```

- `headers` (optional)
  Type: object
  
  Additional headers.
  
  Example:
  
  ```json
  {
    "correlation-id": "1234-4321-1234"
  }
  ```
  
  - `correlation-id` (optional)
    Type: string
    
    The correlation-id header is used for linking one message with another.
    It typically links a reply message with its requesting message.

- `path` (required)
  Type: string
  
  References the part of a Thing which is affected by this message.
  
  Example:
  
  ```json
  "/features/location/properties/longitude"
  ```

- `value` (optional)
  Type: object | string | number | array | boolean
  
  The `value` field contains the actual payload e.g. a sensor value.
  
  oneOf:
    Type: object
  
    Type: string
  
    Type: number
  
    Type: array
  
    Type: boolean

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

Responses:

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

- 400: 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](https://www.eclipse.dev/ditto/protocol-specification.html) message could not be parsed or was missing a required field

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 401: The request could not be completed due to missing authentication.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 403: The request could not be completed. Possible reasons:
  * the caller has insufficient permissions.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 404: 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.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 408: The request could not be completed due to timeout.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 415: The `Content-Type` of the request was not supported.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

## Examples

### cURL

```bash
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
    }
  }
}'
```

### JavaScript

```javascript
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();
```

### Python

```python
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)
```