Messages

Send a message FROM a specific feature of a specific thing

POST

https://ditto.eclipseprojects.io/api/2/things/{thingId}/features/{featureId}/outbox/messages/{messageSubject}

Send a message with the subject messageSubject from the feature specified by the featureId and thingId path parameter. The request body contains the message payload and the Content-Type header defines its type.

The HTTP request blocks until all acknowledgement requests are fulfilled. By default, it blocks until a response to the message is available or until the timeout is expired. If many clients respond to the issued message, the first response will complete the HTTP request.

In order to handle the message in a fire and forget manner, add a query-parameter timeout=0 to the request.

Note that the client chooses which HTTP status code it wants to return. Ditto will forward the status code to you. (Also note that '204 - No Content' status code will never return a body, even if the client responded with a body).

Who

You will need WRITE permission on the root "message:/" resource, or at least the resource message:/features/featureId/outbox/messages/messageSubject. Such permission is managed within the policy which controls the access on the thing.

Send a message FROM a specific feature of a specific thing

curl -X POST 'https://ditto.eclipseprojects.io/api/2/things/string/features/string/outbox/messages/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '""'

const response = await fetch('https://ditto.eclipseprojects.io/api/2/things/string/features/string/outbox/messages/string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: '""',
});

const data = await response.text();

import requests

response = requests.post(
    'https://ditto.eclipseprojects.io/api/2/things/string/features/string/outbox/messages/string',
    data='""'.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

""

{
  "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"
}

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

{
  "acknowledgementLabel1": {
    "status": 200,
    "payload": "OK"
  },
  "acknnowledgementLabelN": {
    "status": 403,
    "payload": "Forbidden"
  }
}

Body

Payload of the message with max size of 250 kB. It can be any HTTP supported content, including binary content.

application/json,application/octet-stream,text/plainstring

string

Example

Parameters

thingIdstringrequiredpath

The ID of a thing needs to follow the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).

featureIdstringrequiredpath

The ID of the feature - has to conform to RFC-3986 (URI)

messageSubjectstringrequiredpath

The subject of the Message - has to conform to RFC-3986 (URI)

timeoutintegerquery

Contains an optional timeout (in seconds) of how long to wait for the message response and therefore block the HTTP request. Default value (if omitted): 10 seconds. Maximum value: 60 seconds. A value of 0 seconds applies fire and forget semantics for the message.

requested-acksstringquery

Contains the "requested acknowledgements" for this request as comma separated list. The HTTP call will block until all requested acknowledgements were aggregated or will time out based on the specified timeout parameter.

The default (if omitted) requested acks is requested-acks=live-response which will block the HTTP call until a subscriber of the live message sends a response.

conditionstringquery

Defines that the request should only be processed if the given condition is met. The condition can be specified using RQL syntax.

Examples

E.g. if the temperature is not 23.9 update it to 23.9:

PUT /api/2/things/{thingId}/features/temperature/properties/value?condition=ne(features/temperature/properties/value,23.9)

body: 23.9

Further example conditions:

?condition=eq(features/temperature/properties/unit,"Celsius")
?condition=ge(features/temperature/properties/lastModified,"2021-08-22T19:45:00Z")
?condition=gt(_modified,"2021-08-05T12:17:00Z")
?condition=exists(features/temperature/properties/value)
?condition=empty(features/temperature/properties/value)
?condition=and(gt(features/temperature/properties/value,18.5),lt(features/temperature/properties/value,25.2))
?condition=or(gt(features/temperature/properties/value,18.5),not(exists(features/temperature/properties/value))

Response

202Accepted

The message was sent (fire and forget).

400Bad RequestAdvancedError

The request could not be completed. Possible reasons:

the thingId does not conform to the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).
at least one of the defined path parameters is valid.

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. You need WRITE permission on the resource message:/features/{featureId}/outbox/messages/{messageSubject}.

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 interact with the messages of referenced thing.

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

412Precondition FailedAdvancedError

A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a failing If-None-Match header for a read request, status 304 will be returned instead.

Response headers

ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

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

413Payload Too LargeAdvancedError

The size of the sent message is larger than the accepted limit of 250 kB.

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

424any

One or more acknowledgement requests in the parameter requested-acks were not fulfilled.

Response fields application/json

acknowledgementLabel1any

Show child attributes

statusintegerrequired

The HTTP status of the acknowledgement

payloadobject | string | number | array | boolean

The payload of the acknowledgement

Show child attributes

One of

object

string

number

array

boolean

Example

{
  "status": 200,
  "payload": "OK"
}

Example

{
  "acknowledgementLabel1": {
    "status": 200,
    "payload": "OK"
  },
  "acknnowledgementLabelN": {
    "status": 403,
    "payload": "Forbidden"
  }
}

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