openapi.rst

OpenAPI

The OpenAPI specification is an open specification for RESTful endpoints. OGC API specifications leverage OpenAPI to describe the API in great detail with developer focus.

The RESTful structure and payload are defined using JSON or YAML file structures (pygeoapi uses YAML). The basic structure is described here: https://swagger.io/docs/specification/basic-structure/

The official OpenAPI specification can be found on GitHub. pygeoapi supports OpenAPI version 3.0.2.

As described in administration, the pygeoapi OpenAPI document is automatically generated based on the configuration file:

The API is accessible at the /openapi endpoint, providing a Swagger-based webpage of the API description..

the pygeoapi demo OpenAPI/Swagger endpoint at https://demo.pygeoapi.io/master/openapi

Using OpenAPI via Swagger

Accessing the Swagger webpage we have the following structure:

Notice that each dataset is represented as a RESTful endpoint under collections.

In this example we will test GET capability of data concerning windmills in the Netherlands. Let's start by accessing the service's dataset collections:

The service collection metadata will contain a description of each collection:

Here, we see that the dutch_windmills dataset is be available. Next, let's obtain the specific metadata of the dataset:

We also see that the dataset has an items endpoint which provides all data, along with specific parameters for filtering, paging and sorting:

For each item in our dataset we have a specific identifier. Notice that the identifier is not part of the GeoJSON properties, but is provided as a GeoJSON root property of id.

This identifier can be used to obtain a specific item from the dataset using the items{id} endpoint as follows:

Using OpenAPI via ReDoc

pygeoapi also supports OpenAPI document rendering via ReDoc.

ReDoc rendering is accessible at the same /openapi endpoint, adding ui=redoc to the request URL.

Summary

Using pygeoapi's OpenAPI and Swagger endpoints provides a useful user interface to query data, as well as for developers to easily understand pygeoapi when building downstream applications.