OGC API - Common SWG

Chair(s):

Maso Pau, Joan (Universitat Autònoma de Barcelona (CREAF))
Heazel, Charles (Heazel, Charles)

Group Charter:

Download Charter document

Group Description:

Purpose of the OGC API - Common Standards Working Group

The purpose of this Standards Working Group is to:

  • Develop and maintain a family of OGC API - Common standards.

  • Develop and maintain extensions of the OGC API - Common standards as identified in the Scope of Work section.

  • Maintain the OWS Common Standard making additions and extensions to that standard as necessary.

The formal proposed name of the new multi-part standard is "OGC API - Common". The short name “Common API” may also be used to refer to this effort in the charter and work products.

Business Value Proposition

The OGC® Open Geospatial APIs - White Paper noted that "The recent proliferation of APIs for geospatial applications has degraded the interoperability previously established by open standards. This degradation is due both to the variability of API practices across the IT industry as well as variability in geospatial APIs specifically. Advancements in API practices is needed across the software development profession". This proliferation of APIs is evidenced, in part, by statistics from the Programmable Web - one of the largest directories of APIs on the Web - which reported in July 2019 that it had seen faster growth than in previous years. With more than 22,000 APIs registered by July 2019, this showed a significant increase from when the directory started tracking APIs in 2005.

There are currently millions of datasets, offered by more than 200,000 servers that implement OGC Web Services (OWS) standards. OGC recognizes that the OWS standards are part of an operational standards baseline that must be maintained. However, there is also recognition within the OGC that Web API technology has advanced in the recent half-decade and therefore offers some capabilities that could benefit OGC Members, their customers and stakeholders. This implies that there is a need for OGC to develop a series of Web API standards that offer similar capabilities to those offered by OWS standards. The OGC API suite of standards have been conceived to address this need. To ensure consistency across OGC API standards, a multi-part standard called OGC API - Common will specify both mandatory and optional capabilities that all implementations of OGC API standards may support.

Scope of Work

OpenAPI frameworks have helped make describing and sharing API definitions more suitable for interoperability standardization. The concept of a Common API was demonstrated in various OGC Innovation Program initiatives.

The OGC API - Common SWG will build on those preliminary efforts to more fully develop and document a family of Common API standards that will provide a modernized, common, and consistent interface to services that aligns with the current architecture of the Web and the Spatial Data on the Web Best Practices (https://www.w3.org/TR/sdw-bp/).

  • Architecture: The OGC API - Common standards will define API building blocks which can be used to construct Web APIs. The purpose of these standards is to make geospatial resources accessible through Web APIs. Additional resource types may also be supported where these resources support the creation, access, and use of Geospatial resources.

  • Encodings: The first version of the Common API will support JSON and HTML as encodings for descriptions of geospatial resources in the API. No encoding will be mandatory and other encodings may be used as well. The HTTP focus is designed to support the use of multiple formats and defines rules about how servers can return the encoding that the client can best handle (“content negotiation”).

  • Reuse: The use of unique Common API resources or components will be minimized and, where available, existing industry-standards or patterns that are commonly used by developers will be used instead.

The primary goal of the Common API SWG is to serve as a coordinating body across the constellation of OGC Web API Standards. Part of that role is to identify API modules which may have common applicability to other OGC API standards and, where appropriate, mature those modules as additional parts of the Common API family of standards.

The "OGC API - Common" SWG will also develop the core of "OGC API - Common" as quickly as possible and work on extensions after that, driven by community interest. An important aspect is to ensure that implementing the standard will lead to efficient implementations, happy developers of both server and client components, and satisfied users of such components.

Before finalizing parts of the future versions of the "OGC API - Common", completion of goals should be verified:

  • Working implementations of all capabilities must be available and tested; and

  • Implementation feedback must be taken into account.

A consequence of this verification is that the period between the availability of what is considered a mature draft and the finalization of the candidate standard may be longer than in the past, depending on the availability of evidence about the suitability of the candidate standard based on implementations. Developers should be encouraged as early as possible to implement the draft API specification and provide feedback. An aspect of this is public access to drafts from the beginning. To this end, the SWG intends to use a public GitHub repository in the development of this standard as this is the environment many developers are familiar with and use on a daily basis.

Statement of relationship of planned work to the current OGC standards baseline

This proposed standard is intended to be a major component of the OGC API framework. The proposed standard will take advantage of Web API patterns identified in OGC API standards (e.g., OGC API – Features) and other ongoing API efforts to better align with current and emerging IT practices.

What is Out of Scope?

Standards are important for interoperability. At the same time, it is important that standards only state requirements that are important for a significantly large group of users. Proposals for new parts of OGC API - Common or change requests to existing parts must identify the user group that will benefit from the proposal and for each proposed conformance class; otherwise the proposal will be considered out-of-scope.

If a community has a need to develop a profile, the profile should be specified and governed by that community and will not be included in the OGC API - Common program of work.

Specific Contribution of Existing Work as a Starting Point

The starting point for the work will be the draft documents that currently are on the proposed SWG’s repository (https://github.com/opengeospatial/oapi_common). This charter also recognizes the prior work done by the OWS Common SWG. Upon approval of this Charter, responsibility for OGC API - Common shall be transferred to the proposed OGC API - Common SWG.

The work shall also be informed by the following specifications and by recommendations found in:

Each of these documents recommends an emphasis on resource-oriented APIs in future OGC standards development including use of tools such as OpenAPI.

 
 

Description of Deliverables

Initial Deliverables

The following deliverables will result from the work of this SWG:

  • A final version of the "OGC API - Common - Part 1: Core" document for submission to the TC;

  • Identification of at least three prototype implementations of the core based on the standard — although more would be preferred; and

  • Zero or more additional parts as time and community interest permits.

Part 1 will cover basic capabilities and define high-level metadata. Capabilities for richer geospatial interfaces or extension for unique geospatial resource considerations will be specified in additional parts.

The targeted start date is in August 2020 once charter is approved. Formal approval of the core Common API is envisaged to take place nearer December 2020.

Additional SWG Tasks

The overarching task of the SWG is to hunt for commonality across the Web API efforts and document those elements as OGC standards.

The SWG will also develop the following extensions:

  • OGC API - Common - Part 2: Geospatial Data

  • OGC API - Common - Part 3: Coordinate Reference Systems

IPR Policy for this SWG

  • ✓ RAND-Royalty Free

  • ❏ RAND for fee

Anticipated Participants

  • Geospatial resource providers.

  • Developers implementing services.

  • Users of geospatial resources.

Domain Working Group Endorsement

The Architecture DWG will review the proof-of-concept at https://github.com/opengeospatial/oapi_common and this SWG charter. A statement of endorsement is anticipated at the September 2020 Virtual OGC Member Meeting.

Other Informative Remarks about this SWG

  1. Similar or Applicable Standards Work (OGC and Elsewhere).

The following standards work may be applicable to the work of the proposed SWG:

  • 06-121r9, OGC Web Service Common Implementation Specification Standard

  • 17-069, OGC API - Features

  • 18-062, OGC API - Processes

  • 19-086, OGC API - Environmental Data Retrieval

  • 19-087, OGC API - Coverages

  • 20-004, OGC API - Records

  • 20-009, OGC API - Styles

  • 20-057, OGC API - Tiles

  • 20-058, OGC API - Maps

Additionally, the proposed SWG will monitor other OGC API work ongoing in various Standards and Innovation Program activities.