Messages

Initiates claiming a specific thing in order to gain access

POST

https://ditto.eclipseprojects.io/api/2/things/{thingId}/inbox/claim

Why

A claiming process may enable an end-user to claim things and proof ownership thereof. Such a process is initially triggered via a claim message. This message can be sent to the things service with the HTTP API or the things-client.

How

At this resource you can send a "claim" message to the thing identified by the thingId path parameter in order to gain access to it. The "claim" message is forwarded together with the request body and Content-Type header to client(s) which registered for Claim messages of the specific thing.

The decision whether to grant access (by setting permissions) is completely up to the client(s) which handle the "claim" message.

The HTTP request blocks until all acknowledgement requests are fulfilled. By default, it blocks until a response to the issued "claim" 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.

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

No special permission is required to issue a claim message.

Example

See Claiming concept in detail and example in GitHub. However, in that scenario, the policy should grant you READ and WRITE permission on the "message:/" resource in order to be able to send the message and read the response. Further, the things-client which handles the "claim" message, needs permission to change the policy itself (i.e. READ and WRITE permission on the "policy:/" resource).

Initiates claiming a specific thing in order to gain access

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

const response = await fetch('https://ditto.eclipseprojects.io/api/2/things/string/inbox/claim', {
  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/inbox/claim',
    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"
}

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

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

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).

timeoutintegerquery

Contains an optional timeout (in seconds) of how long to wait for the Claim response and therefore block the HTTP request. Default value (if omitted): 60 seconds. Maximum value: 600 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.

Response

200OK

The Claim message was processed successfully and the response body contains the custom response. The response body may contain arbitrary data chosen by the recipient. The response code defaults to 200 but may be chosen by the recipient too.

204No Content

The Claim message was processed successfully and no custom response body was set. The response code defaults to 204 but may be chosen by the recipient.

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 invalid

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

404Not FoundAdvancedError

The request could not be completed. Possible reasons:

the referenced thing does not exist.

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

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

429Too Many RequestsAdvancedError

The user has sent too many requests in a given amount of time ("rate limiting").

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