From 159018f8d04a1a4b07e53e1b89d834c61142059d Mon Sep 17 00:00:00 2001 From: Iain Anderson Date: Tue, 7 Dec 2021 14:41:40 +0000 Subject: [PATCH] feat: Device functions ADR Specify asynchronous operation via MessageBus rather than synchronous REST Signed-off-by: Iain Anderson --- .../device-service/0020-invoking-functions.md | 45 ++++++++++++++----- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/docs_src/design/adr/device-service/0020-invoking-functions.md b/docs_src/design/adr/device-service/0020-invoking-functions.md index 8a46d19212..79594e1e41 100644 --- a/docs_src/design/adr/device-service/0020-invoking-functions.md +++ b/docs_src/design/adr/device-service/0020-invoking-functions.md @@ -63,20 +63,43 @@ this is unintuitive. Note: the `attributes` structure is analagous to `attributes` in a `deviceResource`. Each device service should document and implement a scheme of required attributes that will allow for selection of the relevant funtion. The function's `name` is intended for UI and logging purposes and should not be used for actual function selection on the device. -**Add a REST endpoint to the device service for performing functions** +**Define MessageBus topics on which function call requests and replies are to be made** -`api/v2/device-funtion//` +`edgex/function-calls/device/[profile-name]/[device-name]/[function-name]` -This shold accept POST requests with parameters sent in a JSON (or CBOR) payload +The payload for messages on these topics should be of the form +``` +{ + requestId: "184b894f-a7b7-4d6c-b400-99961d462419", + parameters: { (a map of parameter values keyed by parameter name) } +} +``` + +The `requestId` may be any string but UUIDs are recommended. -A successful invocation should return HTTP 200 with the out values in JSON -or CBOR format. +`edgex/function-responses/device/[profile-name]/[device-name]/[function-name]` + +The device service will provide responses to function calls on this topic. The payload will be + +``` +{ + requestId: "184b894f-a7b7-4d6c-b400-99961d462419", + status: 0, + returnValues: { (a map of return values keyed by value name) } +} +``` + +or if a call fails + +``` +{ + requestId: "184b894f-a7b7-4d6c-b400-99961d462419", + status: (nonzero), + errorMessage "Message indicating the nature of the failure" +} +``` -Returnable errors should be +TODO: define status codes for common errors eg not found, locked etc -* BAD REQUEST: parameters were missing, wrong type, or out-of-range -* INTERNAL SERVER ERROR: the DS implementation was unable to fulfill the request -* NOT FOUND: no such device, or no such function -* LOCKED: device or service is locked or down (adminstate, operating state) +** The device SDKs will provide an API for the service implementations to implement these operations ** -**Add a REST endpoint to core-command for performing functions**