2.1.  Core Requirements Class

The requirements specified in the Core Requirements Class are applicable to all OGC API Standards. They assure consistent use of the HTTP protocols, provide rules for the construction of URIs, and define requirements governing the use and processing of URI query parameters. Through these requirements, OGC API — Common seeks to assure that implementations of OGC API Standards will provide a predictable interface for their peers.

The Core requirements class is specified in Clause 8 Core Requirements Class.

2.2.  Landing Page Requirements Class

The requirements specified in the Landing Page Requirements Class provide a minimal useful service interface for an OGC Web API. These resources convey a basic understanding of the API and provide a starting point for further discovery. The requirements specified in this requirements class are recommended for all OGC Web APIs.

The Landing Page requirements class is specified in Clause 9 Landing Page Requirements Class.

2.3.  Encoding Requirements Classes

The OGC API — Common Standard does not mandate a specific encoding or format for representations of resources. However, both HTML and JSON are commonly used encodings for spatial data on the web. The HTML and JSON requirements classes specify the encoding of resource representations using:

• HTML

• JSON

Neither of these encodings is mandatory. An implementer of the API-Common Standard may decide to implement other encodings instead of, or in addition to, these two.

The Encoding Requirements Classes are specified in Clause 10 Encoding Requirements Classes.

2.4.  OpenAPI 3.0 Requirements Class

The OGC API — Common Standard does not mandate any encoding or format for the formal definition of the API. The preferred option is the OpenAPI 3.0 specification. The OpenAPI 3.0 requirements class has been specified for APIs implementing OpenAPI 3.0.

The OpenAPI 3.0 Requirements Class is specified in Clause 11 OpenAPI 3.0 Requirements Class.

2.5.  OGC Building Blocks Registry

To facilitate the discovery and management of the building blocks specified in this and other OGC API Standards, a registry has been established at https://blocks.ogc.org .

6.1.  Web API Fundamentals

The following concepts are critical to understanding OGC Web API Standards.

1. The purpose of a Web API is to provide a uniform interface to resources.

2. Resources are uniquely identified using Uniform Resource Identifiers (URI).

3. A user manipulates a resource through representations of that resource.

4. A representation is the current or intended state of a resource encoded for exchange between components.

5. The format used to encode a representation is negotiated between the components participating in the exchange.

6. Representations are exchanged between components using the HTTP protocol and the operations (GET, PUT, etc.) that HTTP supports.

6.2.  Identifiers

The Architecture of the World Wide Web establishes the URI as the single global identification system for the Web. Therefore, URIs or URI Templates are used in OGC Web API Standards to identify key entities in those Standards.

In accordance with OGC policy, only the Uniform Resource Locator (URL) form of URIs is used.

The normative provisions in this Standard are denoted by the URI http://www.opengis.net/spec/ogcapi-common-1/1.0. All Requirements, Requirements Modules and Conformance Modules that appear in this document are denoted by partial URIs that are relative to this base.

Resources described in this document are denoted by partial URIs that are relative to the root node of the API. This node serves as the head of the resource tree exposed through an API. In OpenAPI, the root node is identified by the url field of the Server Object. In this document the tag {root} designates the root node of a URI.

The partial URIs used to identify Resources in this document are referred to as the resource path. The purpose of a resource path is to identify the referenced resource within the context of this Standard. Implementers are encouraged to use these partial URIs in their implementations, thereby providing a common look and feel to OGC APIs.

The OGC API — Common — Part 1 Standard defines Resources, which may appear in more than one place in the API. These Resource Types are identified by name rather than by URI.

Summary for Developers:

RFC 3986 defines a URI in Backus-Naur Form (BNF) as follows:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

        hier-part     = "//" authority path-abempty
                         / path-absolute
                         / path-rootless
                         / path-empty

        authority     = [ userinfo "@" ] host [ ":" port ]

        path-abempty  = *( "/" segment )

        path-absolute = "/" [ segment-nz *( "/" segment ) ]

        path-rootless = segment-nz *( "/" segment )

        path-empty    = 0<pchar>

Figure 1 — Backus-Naur Definition of URI

The following rules should be used when interpreting the BNF for use with this Standard:

• scheme is assumed to be HTTP or HTTPS;

• authority is provided by the API developer;

• {root} designates the scheme, authority, and path to the root node of the API implementation;

• Only the path-absolute and path-rootless patterns are used;

• Parameters passed as part of an operation are encoded in the query; and

• Parameters passed in HTTP headers or as cookies are out of scope for this Standard.

The following example shows a URI categorized according to RFC 3986 and OGC Web API Standards.

URI     https://example.com:8042/myapi/mydata/?name=roads#centerline
        \____/ \_______________/ \__________/ \_________/ \________/
          |           |               |            |           |
3986    scheme     authority         path         query      fragment
        \______________________/ \__________/ \____________________/
                      |               |                 |
OGC                {root}            path            parameters

Figure 2 — Example URI and Components

This document does not restrict the lexical space of URIs used in the API beyond the requirements of the HTTP and URI Syntax IETF RFCs. If URIs include reserved characters that are delimiters in the URI subcomponent, these have to be percent-encoded. See Clause 2 of RFC 3986 for details.

Additional information on this topic is provided in the OGC API — Common — Users Guide.

6.3.  Links

OGC Web API Standards use RFC 8288 (Web Linking) to express relationships between resources. Resource representations defined in these Standards commonly include a “links” element. A “links” element is an array of individual hyperlink elements. These “links” elements provide a convention for associating related resources.

The individual hyperlink elements that make up a “links” element are defined using the following Hyperlink Schema.

type: object
required:
  - href
  - rel
properties:
  href:
    type: string
    description: Supplies the URI to a remote resource (or resource fragment).
    example: http://data.example.com/buildings/123
  rel:
    type: string
    description: The type or semantics of the relation.
    example: alternate
  type:
    type: string
    description: A hint indicating what the media type of the result of dereferencing the link should be.
    example: application/geo+json
  hreflang:
    type: string
    description: A hint indicating what the language of the result of dereferencing the link should be.
    example: en
  title:
    type: string
    description: Used to label the destination of a link such that it can be used as a human-readable identifier.
    example: Trierer Strasse 70, 53115 Bonn
  length:
    type: integer

Figure 3 — Link Relation Schema

In addition, links should be passed in the response using HTTP link headers. These links are accessible to the client without a need to process the resource.

Additional information on this topic is provided in the OGC API — Common — Users Guide.

6.4.  Link relations

Link relation types identify the semantics of a link. For example, a link with the relation type “service-meta” indicates that the current link context has service metadata at the link target.

Link relation types are expressed using the “rel” property from the Hyperlink Schema.

The “rel” property is populated using values from the IANA Link Relations Registry wherever possible. Additional values are registered with the OGC Link Relation Registry. Additional relation type values can be used if neither of these registers suffice.

The link relationships used in the OGC API — Common — Part 1: Core Standard are described in Table 1. Additional relation types may be used if the implementation warrants it.

Table 1 — Link Relations

Additional information on the use of link relationships is provided in the OGC API — Common — Users Guide.

6.5.  Use of HTTPS

For simplicity, this OGC Standard only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS. This is simply a shorthand notation for “HTTP or HTTPS”. In fact, most servers are expected to use HTTPS and not HTTP.

OGC Web API Standards do not prohibit the use of any valid HTTP option. However, implementers should be aware that optional capabilities that are not in common use could be an impediment to interoperability.

6.6.  API definition

7.1.  Evolution from OGC Web Services

OGC Web Service (OWS) Standards implement a Remote-Procedure-Call-over-HTTP architectural style using XML for payloads. This was the state-of-the-art when OGC Web Services (OWS) were originally designed in the late 1990s and early 2000s. However, technology has evolved. New Resource-Oriented APIs provide an alternative to the Service-Oriented Approach. New OGC Web API Standards are under development to provide API alternatives to the OWS Standards.

The OGC API — Common Standard specifies common modules for defining OGC Web API Standards that follow the current Web architecture. In particular, the recommendations as defined in the W3C/OGC best practices for sharing Spatial Data on the Web as well as the W3C best practices for sharing Data on the Web.

A detailed discussion of OGC Web Services and Web APIs can be found in the OGC API — Common — Users Guide.

7.2.  Modular APIs

A goal of OGC API Standards is to provide rapid and easy access to spatial resources. To meet this goal, the needs of both the resource provider and the resource consumer must be considered. The approach specified in this Standard is to provide a modular framework of API components. This framework provides a consistent “look and feel” across all OGC APIs. When API servers and clients are built from the same set of modules, the likelihood that they will integrate at run-time is greatly enhanced.

The modular Web API approach adopted by OGC API Standards has several facets.

• A common core that is recommended for all implementations of OGC API Standards. This OGC API — Common — Part 1: Core Standard defines this core in the Core Requirements Class.

• Common descriptive resources which allow clients to learn the purpose and capabilities of an API as well as how they should be used. These resources are defined in the Landing Page Requirements Class.

• Clear separation between common requirements and more resource specific capabilities. The OGC API — Common Standard specifies the common requirements that may be relevant to almost anyone who wants to build an API for spatial resources. Resource-specific requirements are addressed in resource-specific OGC Standards.

• Technologies that change more frequently are decoupled and specified in separate modules (“conformance classes” in OGC terminology). This enables, for example, the use/re-use of new encodings for spatial data or API descriptions.

• Modularization is not just about a single “service”. OGC APIs provide building blocks that can be reused in APIs in general. In other words, a server that implements the OGC API – Features Standard should not be seen as a standalone service. Rather, this server should be viewed as a collection of API building blocks that together implement the capabilities that are specified in OGC API — Features. A corollary of this is that it should be possible to implement an API that simultaneously conforms to conformance classes from multiple current or future OGC API Standards.

7.3.  Using APIs

OGC API Standards are expected to support two different approaches that clients may use when accessing an OGC conformant Web API.

In the first approach, clients are implemented with knowledge about the Standard used to build the API and the associated resource types. The clients navigate the resources based on this knowledge and based on the responses provided by the API. The API definition may be used to determine details, e.g., on filter parameters, but this may not be necessary depending on the needs of the client. These are clients that are in general able to use multiple APIs as long as they implement OGC API Standards.

The other approach targets developers that are not familiar with OGC API Standards but want to interact with spatial data provided by an API that happens to implement OGC API Standards. In this case the developer will study and use the API definition — typically an OpenAPI document — to understand the API and implement the code to interact with that API. This assumes familiarity with the API definition language and the related tooling, but it should not be necessary to study the OGC API Standards.

8.1.  HTTP 1.1

The standards used for Web APIs are built on the HTTP protocol. Therefore, conformance with HTTP or a closely related protocol is required.

8.2.  HTTP Status Codes

Table 2 lists the main HTTP status codes that clients should be prepared to receive. This includes support for specific security schemes or URI redirection. In addition, other error situations may occur in the transport layer outside of the server.

Table 2 — Typical HTTP status codes

The return status codes described in Table 2 do not cover all possible conditions. See IETF RFC 7231 for a complete list of HTTP status codes.

When a server encounters an error in the processing of a request, the server may wish to include information in addition to the status code in the response. Since Web API interactions are often machine-to-machine, a machine-readable report would be preferred. IETF RFC 7807 addresses this need by providing “Problem Details” response schemas for both JSON and XML.

8.3.  Query parameters

8.4.  Web Caching

Entity tags are a mechanism for web cache validation and for supporting conditional requests to reduce network traffic. Entity tags are specified by HTTP 1.1 (RFC 7232).

8.5.  Support for Cross-Origin Requests

If the data is located on another host than the webpage (“same-origin policy”), access to data from a HTML page is by default prohibited for security reasons. A typical example is a web-application accessing feature data from multiple distributed datasets.

Two common mechanisms to support cross-origin requests are:

• Cross-origin resource sharing (CORS)

• JSONP (JSON with padding)

8.6.  String Internationalization

If the server supports representing resources in multiple languages, the usual HTTP content negotiation mechanisms apply. The client states its language preferences in the Accept-Language header of a request and the server responds with responses that have linguistic text in the language that best matches the requested languages and the capabilities of the server.

For example, if JSON-LD is used as an encoding, the built-in capabilities to annotate a string with its language should be used.

The link object based on RFC 8288 (Web Linking) includes a hreflang attribute that can be used to state the language of the referenced resource. This can be used to include links to the same data in, for example, English or French. Just like with multiple encodings, a server that wants to use language-specific links will have to support a mechanism to mint language-specific URIs for resources in order to express links to, for example, the same resource in another language. Again, this document does not mandate any particular approach how such a capability is supported by the server.

8.7.  Resource Encodings

A Web API provides access to resources through representations of those resources. One property of a representation is the format used to encode it for transfer. Components negotiate the encoding format to use through the content negotiation process defined in IETF RFC 7231.

Additional content negotiation techniques are allowed, but support is not required of implementations conformant to this Standard.

While this Standard does not specify any mandatory encoding, the following encodings are recommended:

HTML encoding recommendation:

JSON encoding recommendation:

Requirement /req/core/http implies that the encoding of a server response is determined using content negotiation as specified by the HTTP RFC.

The section Media Types includes guidance on media types for encodings that are specified in this document.

Note that any server that supports multiple encodings will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, such as, to alternate representations of the same resource. This Standard does not mandate any particular approach for how this is supported by the server.

As clients simply need to dereference the URI of the link, the implementation details and the mechanism of how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, such as manipulating (“hacking”) URIs in the browser address bar, can study the API Definition document for that server.

Two common approaches are to use:

• An additional path for each encoding of each resource (this can be expressed, for example, using format specific suffixes like “.html”);

• An additional query parameter (for example, “accept” or “f”) that overrides the Accept header of the HTTP request.

8.8.  Parameter Encoding

The following sections provide the requirements and guidelines for encoding parameters for use in an OGC Web API request.

OGC Web API requests are issued using a URI. The URI syntax is defined in IETF RFC 3986. Rules for building URI Templates can be found in IETF RFC 6570.

The Backus-Naur Form (BNF) definition of a URI is provided in Annex Annex D.1.

9.1.  API landing page

An OGC Web API has a single landing page on the {root} node.

The purpose of the landing page is to provide clients with a starting point for using the API. Any resource exposed through an API can be accessed by following paths or links starting from the landing page.

The landing page includes three metadata elements: title, description, and attribution. These three elements describe the API as a whole. Clients can expect to encounter metadata that is more resource-specific as they follow links and paths from the landing page.

While the three metadata elements are defined as text strings, the attribution element is special. Specifically, the attribution element can contain markup text. Markup allows a text string to import images and format text. The capabilities are only limited by the markup language used. See the example landing page for an example of the use of markup in the attribution element.

type: object
required:
  - links
properties:
  title:
    type: string
    title: The title of the API.
    description: While a title is not required, implementers are strongly advised to include one.
    example: Buildings in Bonn
  description:
    type: string
    example: Access to data about buildings in the city of Bonn via a Web API that conforms to the OGC API Common specification.
  attribution:
    type: string
    title: attribution for the API
    description: The `attribution` should be short and intended for presentation to a user, for example, in a corner of a map. Parts of the text can be links to other resources if additional information is needed. The string can include HTML markup.
  links:
    type: array
    items:
      $ref: link.yaml

9.2.  API Definition

Every API implementation should provide an API Definition resource that describes the capabilities provided by that API. This resource can be used by client developers to understand the supported services, by software clients to connect to the server, and by development tools to support the implementation of servers and clients.

9.3.  Declaration of Conformance Classes

The OGC Web API Standards define a collection of modules that can be assembled into a Web API. The first question a client will ask when accessing one of these APIs is “what are you?” In other words, what modules were used to create you? Since implementers have a choice on the modules to use, there is no simple answer. The best that can be done is to provide a list of the modules implemented, a declaration of the Conformance Classes.

The list of Conformance Classes is key to understanding and using an OGC Web API. So it is important that they are easy to access. A simple GET using an easily constructed URI is all that should be required. Therefore, the path to the Conformance Declaration is fixed.

Ease of access is also supported by the structure of the Conformance Declaration resource. It is a simple list of URIs. This is a structure that requires almost no parsing and little interpretation and is designed to be accessible to even the simplest client.

type: object
required:
  - conformsTo
properties:
  conformsTo:
    type: array
    items:
      type: string
      example: "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core"

10.1.  Overview

This clause specifies two requirements classes for encodings that may be used by an OGC Web API implementation. These encodings are commonly used for spatial data on the web applications:

• HTML

• JSON

Neither of these encodings are mandatory. An implementation of the OGC API — Common Standard may implement one, both, or none of them. Other encodings are possible.

10.2.  Requirement Class “HTML”

Geographic information that is only accessible in formats such as GeoJSON or GML have two issues when web application principles are considered:

• The data are not discoverable using Web crawlers and search engines,

• The data cannot be viewed directly in a browser — additional tools are required to view the data.

Therefore, sharing data on the Web should include publication in HTML. To be consistent with the Web, this publication should be done in a way that enables users and search engines to discover and access all of the data.

This is discussed in detail in the W3C/OGC SDW Best Practice. Therefore, the OGC API — Common Standard recommends supporting HTML as an encoding.

10.3.  Requirement Class “JSON”

JSON is a lightweight data-interchange format designed to facilitate structured data interchange between applications. JSON is commonly used for Web-based software-to-software interchanges. Most Web developers are comfortable with using a JSON-based format. Therefore, support for JSON is recommended for machine-to-machine interactions.

An example JSON Schema for the landing page is available at landingPage.yaml.

An example JSON Problem Details report is available at ExceptionExample.yaml.

11.1.  Basic requirements

APIs conforming to this requirements class are self-documenting using an OpenAPI Document.

Two example OpenAPI documents are included in Annex B.

11.2.  Complete definition

Note APIs that, for example, are access-controlled (see Security), support web cache validation, support 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 Clause 8.2.

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

11.3.  Exceptions

Example — An exception response object definition

description: An error occurred.
content:
  application/json:
    schema:
      $ref: http://schemas.opengis.net/ogcapi/common/part1/1.0/openapi/schemas/exception.yaml
  text/html:
    schema:
      type: string

11.4.  Security

OpenAPI uses two constructs to describe the security features of an API; Security Requirements and Security Schemes. Security Requirements are packaged in an array. Only one of the Security Requirements in the array must be met in-order to authorize a request. Security Requirements are associated with one or more Security Schemes. Each Security Scheme describes a security control (ex. HTTP authentication). All of the security schemes associated with a Security Requirement must be satisfied in order for that Security Requirement to be met.

Security Requirements can be defined at the following levels.

• Root — applicable to the whole API except when overridden by Security Requirements defined at a lower level of the API.

• Operation — only applicable to this operation. Overrides any requirements defined at the Root level.

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.

11.5.  Query Parameter Definition

The OpenAPI specification defines query parameters using the Parameter object with the in property set to “query.” The parameter name is a literal value provided by the name property. Since the parameter names are literals, each parameter must be described separately.

OGC API — Common requires that all query parameters are specified in the API definition. In the case of a Feature server, this could mean that every property of every feature type must be described in the API definition, a requirement that few implementers would accept.

The OpenAPI specification provides a capability that allows additional parameters to be specified without explicitly declaring them. That is, parameters that have not been explicitly specified in the API definition for the operation will still be considered “specified” for purposes of validation (see /per/core/query-param-name-specified and /per/core/query-param-name-tolerance.

in: query
name: freeFormParameters
schema:
  type: object
  additionalProperties: true
style: form

Figure 6 — OpenAPI schema for additional "free-form" query parameters

Note that the name of the parameter does not matter as the actual query parameters are the names of the object properties. For example, assume that the value of freeFormParameters is this object:

{
  "my_first_parameter": "some value",
  "my_other_parameter": 42
}

Figure 7 — Example "free-form" query parameter

In the request URI this would be expressed as &my_first_parameter=some%20value&my_other_parameter=42.

11.6.  Further Information

Additional guidance on using OpenAPI in OGC Web API implementations can be found in the OGC API — Common — Users Guide.

12.1.  Normal Response Media Types

The typical media type for all “web pages” in an OGC Web API would be text/html.

The media type that would typically be used in an OGC Web API for machine-to-machine exchanges would be application/json.

12.2.  OpenAPI Media Types

The media types for an OpenAPI definition are application/vnd.oai.openapi+json;version=3.0 (JSON) and application/vnd.oai.openapi;version=3.0 (YAML).

12.3.  Problem Details Media Types

OGC API — Common recommends that implementers use IETF RFC 7807 when constructing the response body for an error condition. The media types for an RFC 7807 Problem Details response body are:

• application/problem+json — for responses in JSON

• application/problem+xml — for responses in XML