-
Notifications
You must be signed in to change notification settings - Fork 215
/
outbox-message.yml
88 lines (84 loc) · 3.67 KB
/
outbox-message.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
# 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: Send a message FROM a specific thing
description: |-
Send a message with the subject `messageSubject` **from** the thing
identified by the `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:/outbox/messages/messageSubject`.
Such permission is managed within the policy which controls the access on the thing.
tags:
- Messages
parameters:
- $ref: '../../parameters/thingIdPathParam.yml'
- $ref: '../../parameters/messageSubjectPathParam.yml'
- $ref: '../../parameters/messageTimeoutParam.yml'
- $ref: '../../parameters/liveMessageRequestedAcksParam.yml'
responses:
'202':
description: The message was sent (fire and forget).
'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'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the resource `message:/outbox/messages/{messageSubject}`.
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.
* the caller has insufficient permissions to interact with the messages of referenced thing.
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'
requestBody:
$ref: '../../requests/payload.yml'