Published

OGC User Guide

•
OGC API - Common - Users Guide
Charles Heazel Editor
Submission Date: 2022-11-09 Approval Date: 2022-02-02 Publication Date: 2023-03-28 External identifier of this OGC® document: http://www.opengis.net/doc/UG/ogcapi-common/1.0 Internal identifier of this OGC® document: 20-071
Version: 1.0.0
Additional Formats: PDF
OGC User Guide

Published

Notice

This document is not an OGC Standard. This document is an OGC User Guide and is therefore not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard.

Further, an OGC User Guide should not be referenced as required or mandatory technology in procurements.

Document number:20-071
Document type:OGC User Guide
Document subtype:
Document stage:Published
Document language:English

Copyright notice

Copyright © 2023 Open Geospatial Consortium
To obtain additional rights of use, visit https://www.ogc.org/legal

Note

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.


License Agreement

Use of this document is subject to the license agreement at https://www.ogc.org/license



I.  Abstract

The OGC API — Common Standard is a multi-part Standard that specifies reusable building-blocks that can be used in the construction of OGC API Standards. The OGC API — Common — Users Guide presents information useful to developers or users of implementations of the OGC API — Common Standard. The information in the Users Guide is not normative. That is, it is not mandatory. However, it may prove essential to fully understand the normative text in the OGC API — Common Standard. The Users Guide is therefore intended to serve as an aid to developers and users.

II.  Keywords

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

OGC document, geographic information, spatial data, API, json, html, OpenAPI, REST, Common


III.  Preface

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the Standard set forth in this document, and to provide supporting documentation.

IV.  Security considerations

No security considerations have been made for this document.

V.  Submitting Organizations

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

VI.  Submitters

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

Table — Submitters

NameAffiliation
Charles Heazel (editor)Heazeltech
Jérôme Jacovella-St-LouisEcere Corporation
Joan MasóUAB-CREAF

OGC API - Common - Users Guide

1.  Scope

The OGC API — Common Standard is a multi-part Standard that specifies reusable building-blocks that can be used in the construction of OGC API Standards. The purpose of the OGC API — Common Standard is to define those fundamental building blocks and requirements which are applicable to all, if not most, OGC Web API Standards.

The OGC API — Common — Users Guide presents information useful to developers or users of implementations of OGC API — Common. The Users Guide focuses on OGC API — Common but is applicable to other OGC API Standards, specifically those OGC API Standards that implement requirements classes from OGC API — Common. The Users Guide discusses the architecture adopted by OGC API — Common, use of identifiers, link relations, OGC API Collections, and the OpenAPI specification.

2.  Terms and definitions

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

For the purposes of this document, the following additional terms and definitions apply.

2.1. Uniform Resource Identifier (URI)

an identifier consisting of a sequence of characters matching the syntax rule named “<URI>”. (IETF RFC 3986)

2.2. Uniform Resource Locator (URL)

the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism (e.g., its network “location”). (IETF RFC 3986)

2.3. Web API

API using an architectural style that is founded on the technologies of the Web. (W3C Data on the Web Best Practices)

2.4. Web Resource

a resource that is identified by a URI.

3.  Abbreviated terms

API

Application Programming Interface

CORS

Cross-Origin Resource Sharing

HTTP

Hypertext Transfer Protocol

HTTPS

Hypertext Transfer Protocol Secure

IANA

Internet Assigned Numbers Authority

OGC

Open Geospatial Consortium

URI

Uniform Resource Identifier

URL

Uniform Resource Locator

YAML

YAML Ain’t Markup Language

4.  Evolution from OGC Web Services

OGC Web Service (OWS) Standards implement a Remote-Procedure-Call-over-HTTP architectural style using XML for payloads [7]. This was the state-of-the-art when OWS Standards 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 [11] [10].

5.  Architecture

The following “architecture” captures the core concepts which inform all OGC API Standards.

5.1.  Datasets

Web APIs implement a Resource Oriented approach to Web-based distributed computing. A coherent set of APIs must be based on a common understanding of the resources to be shared. For OGC API Standards, those resources would be identified using an abstract concept of a geospatial dataset. Such a dataset would have the following characteristics.

  • A dataset can be a vector feature collection, a coverage/imagery, or a collection of datasets (therefore potentially a mix of any of these things).

  • A dataset has associated metadata, including some essential information:

    • Information about what type of dataset it is (vector features (and what type of vector features if limited to one type, e.g., polygons,lines, or points), coverages (values) / imagery (pixels), or sub-datasets— more than one of those things);

    • A textual identifier (e.g., which figures in the resource path);

    • A title (short name / description);

    • Access point for the dataset (could be hosted locally or remote);

    • Geospatial & temporal extent;

    • Resolution/scale;

    • Units/Range/Bit-Depth/Channels/Dimensions etc. for imagery/coverages; and

    • A description of queryables, if applicable.

  • Keywords/Tags, and longer descriptions are also a commonly useful piece of metadata information.

  • Any other ISO 19115 metadata fields can also be associated with the dataset, but are nowhere near as essential to discovering and using geospatial data as those mentioned above. Metadata containing, at a minimum, those essential elements can always be retrieved in ISO 19115-based encodings and potentially other formats.

5.2.  Processes

Processes take one or more datasets as input, add parameters, and produce one or more datasets as output. The following are examples of types of processes that can all run on a server and be invoked by a remote client application:

  1. A complex process built as a container or executable, as typical of implementations of the Web Processing Service (WPS) Standard;

  2. Process description languages such as the Web Coverage Processing Service (WCPS); and

  3. Pre-defined named processes such as ‘vectorization’, ‘buffering’, ‘rasterization’ or ‘rendering of a styled map’.

All of these kinds of processes could share aspects such as taking in an OGC API dataset as input and their output being usable as an OGC API dataset, for direct access and/or asynchronous delivery, and support multiple data partitioning/access mechanisms, estimates/billing elements, and so on.

5.3.  Resource Paths

The resources exposed through implementations of OGC API Standards are accessed through standardized URL templates. These “paths” and their associated resources are described in Table 1. This table documents a selection of the paths and resources as of December 2022. This information will be updated as these and other OGC API Standards mature.

Table 1 — A selection of OGC Dataset Paths from OGC API Standards approved as of 2022-11-08

Path TemplateResource
Common
/collectionsMetadata describing the spatial collections available from this API.
/collections/{collectionId}Metadata describing the collection which has the unique identifier {collectionId}.
Features
/collections/{collectionId}The Feature Collection resource identified by the {collectionId} parameter.
/collections/{collectionId}/itemsThe individual Features in a Feature Collection.
Spatio-temporal environmental data resources
/collections/{collectionId}Identifies a collection of spatio-temporal data with the unique identifier {collectionId}.
/collections/{collectionId}/{queryType}Identifies an Information Resource of type {queryType} associated with the {collectionId} collection.
Tiles
Note: A tile is associated with a resource. {resource} is a place holder for a path segment appropriate for a resource type.
/collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}Feature tile representation of real-world elements at a given resolution restricted by the selected Tile Matrix Set.
/collections/{collectionId}/tiles/{tileMatrixSetId}A description of the TileMatrixSet identified by the {tileMatrixSetId} identifier.
/collections/{collectionId}/tilesAn enumeration of the feature tileset list.
Processes
/processLists the processes this API offers.
/processes/{process-id}Returns a detailed description of a process.
/processes/{process-id}/jobsReturns the running and finished jobs for a process (GET), Executes a process, i.e. creates a new job. Inputs and outputs will have to be specified in a JSON document that needs to be send in the POST body. (POST)
/processes/{process-id}/jobs/{job-id}Returns the status of a job of a process.
/processes/{process-id}/jobs/{job-id}/resultsReturns the result of a job of a process.

6.  Identifiers

The Architecture of the World Wide Web establishes the URI as the single global identification system for the Web [8]. 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 the OGC API – Common – Part 1: Core standard are denoted by the URI http://www.opengis.net/spec/ogcapi-common-1/1.0. All Requirements, Conformance Modules, and Conformance Classes that appear in the standard are denoted by partial URIs that are relative to this base.

Resources described in the standard 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 the OGC API – Common standard the tag {root} designates the root node of a URI.

The partial URIs used to identify Resources in the OGC API – Common standard are referred to by the resource path. The purpose of a resource path is to identify the referenced resource within the context of the standard. Implementors are encouraged to use these partial URIs in their implementations, thereby providing a common look and feel to implementations of OGC API Standards.

This 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 [6] for use with this standard:

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

URI     foo://example.com:8042/myapi/mydata/?name=roads#centerline
        \__/ \______________/\____________/ \_________/ \________/
          |           |            |            |           |
3986    scheme     authority     path         query      fragment
        \__________________________/\_____/\__________/
                      |                |        |
OGC                {root}             path   parameters

Figure 2 — Example URI and Components

The OGC API – Common – Part 1: Core standard 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.

NOTE  OGC Web API standards may include a community-defined identifier as part of a URI (ex. image id or feature id). Definition of the format of those identifiers is out of scope for these standards. Implementers should take care that these identifiers are properly encoded (see RFC 3986) in the URIs for all hosted resources.

8.  What is a Collection?

This section presents a definition for an OGC API Collection, as well as a rationale for such a collection.

8.1.  Definition

<OGC API> Collection
A geospatial data resource that may be available as one or more sub-resource distributions that conform to one or more OGC API Standards.

An OGC API Collection is a restriction on the general concept of a collection.

  1. An OGC API Collection may only contain data. It does not encompass non-data resources (but the Collection resource may still have related auxiliary resources, such as schemas, or processes, as sub-resources).

  2. Geospatial datasets include Spatial Things and/or Temporal Things as data items (but not all data items in the dataset have to have a spatial or temporal extent).

  3. An OGC API Collection has one or more sub-resource distributions.

  4. A distribution provides access to a representation of a dataset.

8.2.  Rationale

Dataset
collection of data

NOTE 1  Published or curated by a single agent, and available for access or download in one or more serializations or formats.

NOTE 2  This definition was adopted as the OGC definition of “dataset” by the OGC Architecture Board (OAB). See OAB issue 1434.

A dataset is a restriction on the general concept of a collection.

  1. A dataset is a collection of data.

  2. A dataset is published or curated by a single agent.

  3. A dataset is available in one or more serializations or formats (distributions).

  4. A distribution is synonymous to the REST concept of a representation.

8.3.  Key Concepts

  • Collection
    A body of resources that belong or are used together. An aggregate, set, or group of related resources. (Derived from Webster’s Dictionary)

  • Distribution
    specific representation of a dataset. (DCAT)

    EXAMPLE: a downloadable file, an RSS feed or an API.

  • Sub-resource Distribution
    a subset of the distribution of a dataset

  • Feature Collection
    a set of Features from a dataset

  • Resource

    1. Any information that can be named. [4]

    2. A conceptual mapping to a set of entities. [4]

    3. A resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are equivalent. [4]

  • Representation

    1. A format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource. [4]

    2. The current or intended state of a resource. [4]

  • Temporal Thing
    Anything with temporal extent, i.e. duration. e.g. the taking of a photograph, a scheduled meeting, a GPS time-stamped track-point. (W3C Basic Geo)

9.  Using OpenAPI (Informative)

The following section describes the main components of an OpenAPI document and how they should be used to construct API requests. The authoritative source is the OpenAPI 3.0 standard available here.

9.1.  OpenAPI Document (root)

The OpenAPI document (Root) contains descriptive information about the API and serves as the root for the other parts of the document.

9.2.  Paths

All API resources are accessed through a path. The Paths field of the OpenAPI document defines all of the paths available through this API. The Paths field is a collection of Paths Objects. Each Paths Object includes the URL or URL template for this path, any Server Objects specific to this Path, Parameters which are applicable to this Path, and an Operation Object for each of the HTTP Verbs applicable to this Path.

9.3.  Operations

Operation Objects provide the details needed to create an HTTP request and response. Specifically, they provide definitions of the request message (including parameters) and all possible responses. In addition, they define any operation specific Server Objects or Security Requirements.

9.4.  Parameters

Parameter Objects describe parameters which can be used in an API. These objects provide the parameter name, where it is passed (query, header, path, or cookie), and a detailed description of its structure (if needed).

Parameter Objects can be defined at the following levels.

  • Path — applicable to all operations on this path.

  • Operation — only applicable to this operation. Overrides any parameters defined at the Path level which have the same name.

9.5.  Servers

An API is not restricted to a single server. Furthermore, the set of valid servers may be different for different sections of the API. An OpenAPI Server Object describes a single server. Most importantly, it provides the URL to that server. Server Objects are grouped into arrays. These arrays provide a list of the servers which can be used to access a section of the API.

servers:
  - url: https://dev.example.org/
    description: Development server
  - url: https://data.example.org/
    description: Production server

Figure 4 — Example Array of Server Objects

Server Objects can be defined at the following levels.

  • Root — applicable to the whole API unless overridden.

  • Path — applicable to all operations on this path. Servers defined at the Root level are still valid.

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

9.5.1.  Building URLs

An OpenAPI document can describe a large number of URLs. Extracting all of the URLs is a non-trivial task. The OpenAPI objects used to construct URLs are:

  • Server Objects (URL template for the root and variables to populate it);

  • Paths Objects (URL template for the path and parameters); and

  • Operation Objects (including parameters).

They are organized as follows:

{Server Object}/{Path Object}/?{Query Parameters}

Server Objects may be found at the OpenAPI document, Path Object, and Operation Object level. Given this potentially large number of servers, how do you create the valid paths?

We can assume that if a Server Object is included, there must be a reason for its presence. So, the Server Objects with the most restrictive scope are the ones we should use. Clients should look for Server Objects in the following order:

  1. The Operation Object,

  2. Then Path Item,

  3. The root.

The first scope where a Server Object is found dictates the behavior completely.

IF Server Objects are supplied
     THEN save them for latter
     ELSE create a Server Object for the host of the OpenAPI document
 DO FOR each Path
     IF Server Objects are included, THEN
         Use them instead of those previously identified
     IF Parameter Objects are included, THEN
         save them for latter
     DO FOR Each Operation
         IF Server Objects are included, THEN
             Use them instead of those previously identified
         IF Parameter Objects are included THEN
             IF this parameter was previously defined
                 THEN replace the previous definition
                 ELSE add this parameter to the set.
         DO FOR Each Server Object
             Extract all URL roots
             DO FOR each URL root
                 Concatenate the URL root and Path to create a working URL
                 Concatenate the working URL with the Parameters
                 Save the completed URL for future use
             CONTINUE
         DONE
     DONE
 DONE

Figure 5 — Algorithm for building a URL


Annex A
(informative)
Revision History

Table A.1

DateReleaseEditorPrimary clauses modifiedDescription
2021-06-010.1C. Heazelallinitial version
2022-11-080.2G. Hobonaallrevision

Bibliography

[1]  IETF RFC 8288: Web Linking, https://tools.ietf.org/html/rfc8288

[2]  IETF RFC 3987: Internationalized Resource Identifiers (IRIs), https://tools.ietf.org/html/rfc3987

[3]  IETF RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, https://tools.ietf.org/html/rfc2046

[4]  Fielding, Roy Thomas: Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000, https://www.ics.uci.edu/fielding/pubs/dissertation/fielding_dissertation.pdf

[6]  ISO/IEC 14977:1996(E): Information technology – Syntactic metalanguage – Extended BNF, available from ISO.

[7]  Whiteside, A., Greenwood, J.: OGC Web Services Common Standard, version 2.0, OGC 06-121r9

[8]  W3C: Architecture of the World Wide Web, Volume One, W3C Recommendation, 15 December 2004, https://www.w3.org/TR/webarch/

[9]  W3C: Data Catalog Vocabulary (DCAT) — Version 2, W3C Recommendation, 04 February 2020, https://www.w3.org/TR/vocab-dcat-2/

[10]  W3C: Data on the Web Best Practices, W3C Recommendation, 31 January 2017, https://www.w3.org/TR/dwbp/

[11]  W3C/OGC: Spatial Data on the Web Best Practices, W3C Working Group Note, 28 September 2017, https://www.w3.org/TR/sdw-bp/

[12]  IETF RFC 3986: Uniform Resource Identifier (URI): Generic Syntax. https://tools.ietf.org/html/rfc3986