II.  Keywords

The following are keywords to be used by search engines and document catalogues.

process, instance, spatial, data, openapi, job, create, update, delete, add, remove, REST, PATCH, POST, DELETE

III.  Security Considerations

See OGC API — Processes — Part 1: Core, Clause 10.4.

Since creating and updating jobs will change the jobs available to a client, servers will — in almost all cases — restrict the access to these operations.

Users making modifications to process resources need to:

The API definition, as defined in Clause 7.3 from OGC 18-062r2, 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 exposed by the serve will declare the authentication schemes that an implementation of the Processes — Part 4 (JM) 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.

Example — Example OpenAPI definition with security requirements

{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "My API",
    "description" : "This API ...",
    "version" : "1.0.0"
  },
  "servers" : [ {
    "url" : "https://example.com/api/v1"
  } ],
  "security" : [ {
    "JWT" : [ ],
    "api_key": [ ]
  } ],
  "paths" : { },
  "components" : {
    "securitySchemes": {
      "JWT" : {
        "type" : "http",
        "scheme" : "bearer",
        "bearerFormat" : "JWT"
      },
      "api_key" : {
        "type": "apiKey",
        "name": "X-API-Key",
        "in": "header"
      }
    }
  }
}

If the authentication of a secured request fails or if the user does not have sufficient privileges, the API endpoint will return an error.

In case the request does not include information to authenticate the user, the server will respond with a 401 response (“Unauthorized”). The response will include a “WWW-Authenticate” header with hints as to how authentication credentials are provided.

Client                                                        Server
  |                                                             |
  |  POST /jobs/xxxx-xxx-xxx-xxxxx   HTTP/1.1                   |
  | ----------------------------------------------------------->|
  |                                                             |
  |  HTTP/1.1  401 Unauthorized                                 |
  |  Date: Mon, 23 May 2022 11:18:45 GMT                        |
  |  WWW-Authenticate: Bearer realm="my-realm"                  |
  |  WWW-Authenticate: ApiKey header="X-API-Key"                |
  |  Content-Type: application/problem+json                     |
  |  Vary: Accept                                               |
  |  Content-Length: 86                                         |
  |                                                             |
  |  {                                                          |
  |    "status": 401,                                           |
  |    "title": "Unauthorized",                                 |
  |    "detail": "HTTP 401 Unauthorized"                        |
  |  }                                                          |
  | <-----------------------------------------------------------|

Listing 1 — Unauthorized request

If valid authentication credentials have been provided, but the API refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response (“Forbidden”).

Client                                                              Server
  |                                                                   |
  | POST /jobs/xxxx-xxx-xxx-xxxxx HTTP/1.1                            |
  | Host: example.com                                                 |
  | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ97HgQ    |
  |------------------------------------------------------------------>|
  |                                                                   |
  | HTTP/1.1 403 Forbidden                                            |
  | Date: Mon, 23 May 2022 11:18:55 GMT                               |
  | Content-Type: application/problem+json                            |
  | Vary: Accept                                                      |
  | Content-Length: 80                                                |
  |                                                                   |
  | {                                                                 |
  |   "status" : 403,                                                 |
  |   "title" : "Forbidden",                                          |
  |   "detail" : "HTTP 403 Forbidden"                                 |
  | }                                                                 |
  |<------------------------------------------------------------------|

Listing 2 — Forbidden request

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decide to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response (“Not Found”) to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

IV.  Submitting Organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

V.  Submitters

All questions regarding this submission should be directed to the editors or the submitters:

Annex A
(normative)
Abstract Test Suite

Annex B
(informative)
Revision History