OpenAPI¶

OpenAPI spec is an open specification for REST end points, currentely OGC services are being redefined using such specification. The REST structure and payload are defined using yaml file structures, the file structure is described here: https://swagger.io/docs/specification/basic-structure/

pygeoapi REST end points descriptions on OpenAPI standard are automatically generated based on the configuration file:

pygeoapi generate-openapi-document -c local.config.yml > openapi.yml

The api will them be accessible at /openapi endpoint.

For api demo please check: https://demo.pygeoapi.io/master/openapi

The api page has REST description but also integrated clients that can be used to send requests to the REST end points and see the response provided

Using OpenAPI¶

Acessing the openAPI webpage we have the following structure:

Please notice that each dataset will be represented as a REST end point under collections

In this example we will test and GET data concerning windmills in the Netherlands, first we will check the avaiable datasets, by accessing the service’s collections:

The service collection metadata will contain a description of the collections provided by the server

_images/openapi_get_collections_result.png

The dataset dutch_windmills will be available on the collections end point, in the following example we’ll obtain the specific metadata of the dataset

_images/openapi_get_collection_result.png

features/items composing the data are agregated on the /items end point, in this REST end point it is possible to obtain all dataset, or restrict it features/items to a numerical limit, bounding box, time stamp, pagging (start index)

For each feature in dataset we have a specific identifier (notice that the identifier is not part of the JSON properties),

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