| # 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 feature of a specific thing |
| description: |- |
| 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. |
| tags: |
| - Messages |
| parameters: |
| - $ref: '../../parameters/thingIdPathParam.yml' |
| - $ref: '../../parameters/featureIdPathPathParam.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://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)). |
| * at least one of the defined path parameters is valid. |
| 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:/features/{featureId}/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' |
| '503': |
| $ref: '../../responses/messageTimeout.yml' |
| requestBody: |
| $ref: '../../requests/payload.yml' |