diff --git a/extensions/deploy_replace_undeploy/standard/20-044.adoc b/extensions/deploy_replace_undeploy/standard/20-044.adoc index b365f121..af0779de 100644 --- a/extensions/deploy_replace_undeploy/standard/20-044.adoc +++ b/extensions/deploy_replace_undeploy/standard/20-044.adoc @@ -11,7 +11,7 @@ :issued-date: yyyy-mm-dd :external-id: http://www.opengis.net/doc/IS/ogcapi-processes-2/1.0 :keywords: process, collection, instance, spatial, data, openapi, transactions, insert, update, delete, add, remove, deploy, undeploy, REST, PUT, POST, DELETE -:submitting-organizations: Geolabs; CubeWerx Inc; Terradue Srl.. +:submitting-organizations: Geolabs; CubeWerx Inc; Terradue Srl.; Wuhan University (WHU).; Computer Research Institute of Montréal (CRIM). :editor: Panagiotis (Peter) A. Vretanos, Gérald Fenoy :mn-document-class: ogc :mn-output-extensions: xml,html,doc,pdf diff --git a/extensions/deploy_replace_undeploy/standard/recommendations/deploy-replace-undeploy/deploy/REC_body-cwl.adoc b/extensions/deploy_replace_undeploy/standard/recommendations/deploy-replace-undeploy/deploy/REC_body-cwl.adoc index 45d0753e..42a57baf 100644 --- a/extensions/deploy_replace_undeploy/standard/recommendations/deploy-replace-undeploy/deploy/REC_body-cwl.adoc +++ b/extensions/deploy_replace_undeploy/standard/recommendations/deploy-replace-undeploy/deploy/REC_body-cwl.adoc @@ -10,6 +10,6 @@ part:: The media type `application/cwl` SHALL be used to indicate that request b part:: If the CWL contains more than one workflow, an additional `w` query parameter MAY be used to reference the workflow id to be deployed. -part:: The server SHOULD validate the CWL at the request time. In case, the server cannot find the `w` identifier within the workflow from the CWL provided, a 400 status code is expected with the type "workflow-not-found". +part:: If the `w` parameter has a value, the server SHOULD validate the CWL at the request time. If the server cannot find the `w` identifier within the workflow from the CWL provided, it SHOULD return a 400 status code with an exception having type "workflow-not-found." ==== diff --git a/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc b/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc index a8606325..44af1ba3 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/annex_ats.adoc @@ -8,7 +8,7 @@ OGC Web Application Programming Interfaces (APIs) are not Web Services in the tr The Web API under test can require authorization. Any Executable Test Suite implementing this test suite should implement the following security schemes supported by OpenAPI 3.0: HTTP Authorization schemes "basic" and "bearer", API keys, and OAuth2 flow "authorizationCode". -The following requirement apply for a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy under test: +The following requirements apply for a server implementing the OGC API — Processes — Part 2: Deploy, Replace, Undeploy under test: include::../abstract_tests/dru/ATS_mutable-process.adoc[] diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc index 4f25343f..0218e57e 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc @@ -2,11 +2,11 @@ [abstract] == Abstract -OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The <> is used to define the API building blocks. +OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. The <> is used to define the API building blocks. -OGC API Processes provides API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate standard. +The OGC API Processes Standard (aka Processes API) defines API building blocks to describe, execute, monitor and retrieve results of Web-accessible processes. OGC API Processes is comprised of multiple parts, each of them is a separate OGC Standard. -This part extends the core capabilities specified in <> with the ability to dynamically add, modify and/or delete individual processes from a processes API endpoint. +OGC API - Processes - Part 2: Deploy, Replace, Undeploy extends the core capabilities specified in OGC API - Processes - Part 1: Core [<>] with the ability to dynamically add, modify and/or delete individual processes using an implementation (endpoint) of the OGC API - Processes Standard. CAUTION: This is a DRAFT version of the 2nd part of the OGC API - Processes standards. This draft is not complete and there are open issues that are still under discussion. diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_12_security_considerations.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_12_security_considerations.adoc index c4dd8ebc..1207e44b 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_12_security_considerations.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_12_security_considerations.adoc @@ -10,11 +10,11 @@ Users making modifications to process resources need to: . Have "modification privileges" on the processes offered through the API, . Have access to one or more of the POST, PUT and/or DELETE methods on the processes / processes/{processId} endpoints. -The API definition must reflect this in the resource paths and their available methods. +The API definition, as defined in Clause 7.3 from <>, must reflect this in the resource paths and their available methods. Examples in the Clauses specifying the requirements classes focus on the mechanics of the POST, PUT, and DELETE methods and exclude authentication. Since authentication will typically be required for all DRU requests, this section provides some examples/guidance: -The OpenAPI definition will declare the authentication schemes that an implementation of the Processes - Part 2 (DRU) supports for each operation (or for all operations in the API implementation). +The OpenAPI definition exposed by the serve will declare the authentication schemes that an implementation of the Processes - Part 2 (DRU) supports for each operation (or for all operations in the API implementation). A member "security" in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual DRU operations can override this default by providing a "security" member for the individual operation. diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_1_scope.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_1_scope.adoc index d58afcde..9d9dc8dd 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_1_scope.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_1_scope.adoc @@ -1,14 +1,9 @@ == Scope The OGC API - Processes - Part 2 Standard is an extension to the OGC API – Processes – Part 1: Core Standard [<>] and defines the behavior of a server that -supports the ability to dynamically add, replace and/or undeploy processes from via an OGC API - Processes implementation instance. +supports the ability to dynamically add, replace and/or undeploy processes via an OGC API - Processes implementation instance. - -This document specifies an extension that defines the behaviour of a server -that supports operations to deploy, replace or undeploy individual processes -from an OGC API Processes. - -Specifically, this document specifies: +Specifically, the Processes Part 2 Standard specifies: * How to deploy a new process. @@ -17,11 +12,11 @@ Specifically, this document specifies: * How to undeploy an existing process. The following table crosswalks each of the resource endpoints discussed in this -standard with the HTTP methods POST, PUT and DELETE. Each intersecting +Standard with the HTTP methods POST, PUT and DELETE. Each intersecting cell in the table either contains the name of the operation for that combination of resource endpoint and HTTP method, or it contains the -phrase "n/a" which is used to indicate that this specification does not -specify any behaviour for that combination of resource endpoint and HTTP +phrase "n/a" which is used to indicate that this Standard does not +specify any behavior for that combination of resource endpoints and the HTTP method. [#endpoint_method_matrix,reftext='{table-caption} {counter:table-num}'] diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_2_conformance.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_2_conformance.adoc index 895d93ae..162d3a45 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_2_conformance.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_2_conformance.adoc @@ -3,8 +3,6 @@ The OGC API - Processes - Part 2 Standard defines the following requirements classes. -The standardization target is "Web APIs". - The main requirements class is: * <>. @@ -12,12 +10,12 @@ The main requirements class is: This class specifies requirements that any Web API implementing Processes Part 2 must conform with. The `Deploy, Replace, Undeploy` class does not mandate a specific encoding or -format for the formal definition of a process. However, this extension +format for the formal definition of a process. However, the Part 2 extension defines the following conformance class: * <> -for this purpose. The `OGC Application Package` class defines the schema of a +The `OGC Application Package` class defines the schema of a document that formally defines the inputs, outputs and other necessary metadata about a process that is to be dynamically deployed through the API. diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_4_terms_and_definitions.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_4_terms_and_definitions.adoc index 67996db5..7807e494 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_4_terms_and_definitions.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_4_terms_and_definitions.adoc @@ -5,21 +5,21 @@ ==== Execution unit -An execution unit is a component that contains a process that an implementation of the Processes API can run. +A component containing a process that an implementation of the Processes API Part 1 can run. ==== Deploy -Deploy is a verb describing the operation of installing the desired execution unit and associated process description on a Processes API implementation so that the client applications can use the OGC API - Processes - Part 1 Standard to interact with these components as a process. +Deploy refers to installing a desired execution unit onto a Processes API server so that client applications can interact with it as a process using the Processes API Part 1 Standard. ==== Replace -Replace is a verb that describes the operation of upgrading a deployed process, its associated execution unit, and its process description from a Processes API implementation. +Replace refers to upgrading a deployed process from a Processes API implementation. ==== Undeploy -Undeploy is a verb that describes removing a deployed process, its associated execution unit, and process description from a Processes API implementation so that it does not appear anywhere except in the jobs list, potentially. +Undeploy refers to removing a deployed process from a Processes API implementation so that it does not appear as an available process. === Abbreviated Terms CWL:: Common Workflow Language - +DRU:: Deploy, Replace, Undeploy diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc index 45ea5d6f..93cbf23a 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_6_deploy_replace_undeploy.adoc @@ -5,32 +5,32 @@ include::../requirements/requirements_class_deploy-replace-undeploy.adoc[] -A server that implements the DRU conformance class provides the ability to -dynamically deploy, replace and undeploy processes from a processes API. +A server that implements the DRU requirements class provides the ability to +dynamically deploy, replace and undeploy processes. The HTTP POST method is used to deploy a new process to the API. The HTTP PUT method is used to replace the definition of a previously deployed processes that are accessible via the Processes API endpoint. -Finally, the HTTP DELETE method is used to undeploy a previously deployed process that is accessible via the API. +Finally, the HTTP DELETE method is used to undeploy a previously deployed process that is accessible via the Processes API endpoint. Deploying or replacing a process requires that a formal description of the new or -replacement process be provided by the client. This extension does not +replacement process be provided by the client. This Standard does not mandate that a specific processes description language or vocabulary be used. However, to promote interoperability, this extension defines two conformance classes: * <>, that defines a formal process description language encoded using JSON, - * <>, that enables support for CWL-encoded process definition, + * <>, that enables support for CWL-encoded process definition. -A recommendation is made later in this Standard that all implementations of Processes - Part 2 extension support the `OGC Application Package`. +A recommendation is made later in this Standard that all implementations of Processes API Part 2 extension support the `OGC Application Package`. [[deploy-replace-undeploy-http_status_codes]] ==== HTTP status codes -Clients implementing the Processes - Part 2 should be prepared to handle any legal HTTP or HTTPS status code. +Clients implementing the Processes API Part 2 should be prepared to handle any legal HTTP or HTTPS status code. -The *Status Codes* listed in <> are of particular relevance to implementors of this standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in <> are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations. +The *Status Codes* listed in <> are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in <> are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations. [[status_codes]] .Typical HTTP status codes @@ -165,7 +165,7 @@ include::../requirements/deploy-replace-undeploy/deploy/REQ_response-immutable.a The following diagram illustrates the sequence diagram for replacing a previously deployed processes. The identifier of the process does not change. -NOTE: The new process definition replaces to old process definition. Version control is not discussed in this Standard. +NOTE: The new process definition replaces the old process definition. Version control is not discussed in this Standard. ``` Client Server diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc index 8ac931a8..d470dc18 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_7_apppkg.adoc @@ -6,18 +6,15 @@ include::../requirements/requirements_class_ogcapppkg.adoc[] -This conformance class defines the schema of an `OGC Application Package`. An +This requirements class defines the schema of an `OGC Application Package`. An `OGC Application Package` is a document that describes a process in sufficient detail so that an implementation of this extension can dynamically deploy the -process and make it available for execution via an OGC API - Processes implementation. - -An `OGC Application Package` document provides all the information necessary to -deploy a process and make it accessible through the OGC API - Processes API. +process and make it accessible via an OGC API - Processes implementation. The information contained in an `OGC Application Package` can include: * A formal description of the process including what inputs the process takes and what outputs the process generates. -* Either inline or by reference an execution unit which is the `code` that the server needs to execute whenever the process is invoked. +* Either an inline or by reference execution unit which is the `code` that the server needs to execute whenever the process is invoked. * Additional resource information required by the execution unit. === OGC Application Package schema diff --git a/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc b/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc index dae1e5aa..f0832d25 100644 --- a/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc +++ b/extensions/deploy_replace_undeploy/standard/sections/clause_9_cwl.adoc @@ -7,7 +7,7 @@ include::../requirements/requirements_class_cwl.adoc[] A server that implements the CWL Requirement Class SHALL support the use of CWL encoding when interacting with the Processes API Part 2 deploy-replace-undeploy extension endpoint. -In consequence, the following recommandations defined in Recommendation 2 and Recommandation 4 become requirements: +In consequence, the following recommandations defined in <>, <> and <> become requirements: * <> * <>