Skip to content

clause_12_oas.adoc

Latest commit

 

History

History
80 lines (49 loc) · 3.56 KB

clause_12_oas.adoc

File metadata and controls

80 lines (49 loc) · 3.56 KB

OpenAPI requirements classes

Requirements Class "OpenAPI Specification"

Note
 This requirements class is abstract. Implementations can only conform to the concrete requirements classes OpenAPI Specification 3.0 or OpenAPI Specification 3.1.

Basic requirements

Servers conforming to this requirements class define their API by an OpenAPI Document. Note that this requirements class is not specific to a particular version of the OpenAPI specification. Requirements specific to a particular version are defined in separate, dependent requirements classes.

The requirements /req/core/landingpage-success and /req/core/api-definition-success in Core require that the API definition documents are referenced from the landing page.

OpenAPI definitions can be created using different approaches. A typical example is the representation of the feature collections. One approach is to use a path parameter collectionId, i.e., the API definition has only a single path entry for all feature collections. Another approach is to explicitly define each feature collection in a separate path and without a path parameter, which allows to specify filter parameters or explicit feature schemas per feature collection. Both approaches are valid.

Complete definition

Note that servers that, for example, are access-controlled (see Security), support web cache validation, CORS or that use HTTP redirection will make use of additional HTTP status codes beyond regular codes such as 200 for successful GET requests and 400, 404 or 500 for error situations. See [http_status_codes].

Clients have to be prepared to receive responses not documented in the OpenAPI definition. For example, additional errors can occur in the transport layer outside of the server.

Exceptions

Example 1. An example exception response object definition
description: An error occurred.
content:
  application/json:
    schema:
      $ref: http://schemas.opengis.net/ogcapi/processes/part1/2.0/openapi/schemas/common-core/exception.yaml
  text/html:
    schema:
      type: string

Security

The OpenAPI specification currently supports the following security schemes:

  • HTTP authentication,

  • an API key (either as a header or as a query parameter),

  • OAuth2’s common flows (implicit, password, application and access code) as defined in RFC6749, and

  • OpenID Connect Discovery.

Requirements Class "OpenAPI Specification 3.0"

Servers conforming to this requirements class define their API by an OpenAPI 3.0 Document.

Requirements Class "OpenAPI Specification 3.1"

Servers conforming to this requirements class define their API by an OpenAPI 3.1 Document.
⚡