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..
See also
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:
![_images/openapi_intro_page.png](_images/openapi_intro_page.png)
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:
![_images/openapi_get_collections.png](_images/openapi_get_collections.png)
The service collection metadata will contain a description of each collection:
![_images/openapi_get_collections_result.png](_images/openapi_get_collections_result.png)
Here, we see that the dutch_windmills
dataset is be available. Next, let’s obtain the specific metadata of the
dataset:
![_images/openapi_get_collection.png](_images/openapi_get_collection.png)
![_images/openapi_get_collection_result.png](_images/openapi_get_collection_result.png)
We also see that the dataset has an items
endpoint which provides all data, along with specific parameters for
filtering,
paging and sorting:
![_images/openapi_get_item.png](_images/openapi_get_item.png)
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
.
![_images/openapi_get_item_id.png](_images/openapi_get_item_id.png)
This identifier can be used to obtain a specific item from the dataset using the items{id}
endpoint as follows:
![_images/openapi_get_item_id2.png](_images/openapi_get_item_id2.png)
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.