-
Notifications
You must be signed in to change notification settings - Fork 215
/
inbox-claim.yml
107 lines (100 loc) · 4.63 KB
/
inbox-claim.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
# Copyright (c) 2020 Contributors to the Eclipse Foundation
#
# See the NOTICE file(s) distributed with this work for additional
# information regarding copyright ownership.
#
# This program and the accompanying materials are made available under the
# terms of the Eclipse Public License 2.0 which is available at
# http://www.eclipse.org/legal/epl-2.0
#
# SPDX-License-Identifier: EPL-2.0
post:
summary: Initiates claiming a specific thing in order to gain access
description: |-
### 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](https://websites.eclipseprojects.io/ditto/protocol-specification-things-messages.html#sending-and-handling-claim-messages) 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).
tags:
- Messages
parameters:
- $ref: '../../parameters/thingIdPathParam.yml'
- $ref: '../../parameters/messageClaimTimeoutParam.yml'
- $ref: '../../parameters/liveMessageRequestedAcksParam.yml'
responses:
'200':
description: |-
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.
'204':
description: |-
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.
'400':
description: |-
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](https://websites.eclipseprojects.io/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined path parameters is invalid
content:
application/json:
schema:
$ref: '../../schemas/errors/advancedError.yml'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '../../schemas/errors/advancedError.yml'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
content:
application/json:
schema:
$ref: '../../schemas/errors/advancedError.yml'
'408':
description: The request could not be completed due to timeout.
content:
application/json:
schema:
$ref: '../../schemas/errors/advancedError.yml'
'413':
$ref: '../../responses/messageTooLarge.yml'
'424':
$ref: '../../responses/dependencyFailed.yml'
'429':
description: |-
The user has sent too many requests in a given amount of time ("rate
limiting").
content:
application/json:
schema:
$ref: '../../schemas/errors/advancedError.yml'
requestBody:
$ref: '../../requests/payload.yml'