diff --git a/extensions/remote-udp/README.md b/extensions/remote-udp/README.md index 27e535b8..1f81e704 100644 --- a/extensions/remote-udp/README.md +++ b/extensions/remote-udp/README.md @@ -22,23 +22,25 @@ This makes it possible for this extension to add additional allowed values to th This extension extends the `namespace` property of process graph nodes so that it accepts **absolute** URL with the protocols `https` (**recommended**) and `http` (discouraged). The URLs specified MUST return one of the following two options: -1. A single process, compatible to the endpoint `GET /process_graphs/{process_graph_id}`. +1. A single process, compatible\* to the endpoint `GET /process_graphs/{process_graph_id}`. In this case, the `id` property of the process graph node MUST be equal to the `id` of the process, otherwise a `ProcessNamespaceInvalid` error is thrown -2. A list of processes, compatible to the endpoint `GET /process_graphs`. +2. A list of processes, compatible\* to the endpoint `GET /process_graphs`. In this case, the `id` property of the process graph node is used to identify the process from the list. If not found a `ProcessNamespaceInvalid` error is thrown -### Compatibility +\* Compatible means in this context that the requests and responses must comply to the openEO API specification with the following exceptions: -Compatible means in this context that the requests and responses must comply to the openEO API specification with the following exceptions: - -- The `Authorization` header MUST NOT not be sent. -- Lists of processes MUST NOT paginate and the full process description MUST be provided for each process (i.e., the recommendation to omit large properties such as `process_graph` doesn't apply). +- User credentials / tokens that are obtained through the openEO API MUST NOT not be sent to URIs that are hosted external to the openEO API. + The requirement to provide an `Authorization` header for the respective endpoints doesn't apply. +- For a list of processes, the full process description MUST be provided for the process with the given ID within the first request. + This means that the recommendation to omit large roperties such as `process_graph` doesn't apply. + It also requires that the requester doesn't need to paginate through additional pages to find the process with the given ID. + Ideally, the list of processes is not paginated as otherwise the process with the given ID may move to other pages over time. ### Client Considerations -Clients MUST only offer this functionality to users if the conformance class of this extension is listed in the `conformsTo` property of the `GET /` endpoint. +If a client is conncected to a specific backend, the client MUST only offer this functionality to users if the conformance class of this extension is listed in the `conformsTo` property of the `GET /` endpoint. The protocol `http` is discouraged for URLs as web-based clients may not be able to retrieve HTTP URLs from a HTTPS context. For the same reason it is also RECOMMENDED to enable CORS for all URLs. @@ -57,11 +59,11 @@ An exemplary process graph node: ```json { - "process_id": "echo", - "namespace": "https://hub.openeo.org/processes/echo", - "arguments": { - "message": "Hello World" - }, - "result": true + "process_id": "echo", + "namespace": "https://hub.openeo.org/processes/echo", + "arguments": { + "message": "Hello World" + }, + "result": true } ```