Tom Kralidis
77 lines
2.8 KiB
ReStructuredText
77 lines
2.8 KiB
ReStructuredText
.. _openapi:
|
|
|
|
OpenAPI
|
|
=======
|
|
|
|
The `OpenAPI specification <https://swagger.io/docs/specification/about/>`_ 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 <https://github.com/OAI/OpenAPI-Specification/tree/main/versions>`_.
|
|
pygeoapi supports OpenAPI version 3.0.2.
|
|
|
|
As described in :ref:`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..
|
|
|
|
.. seealso::
|
|
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:
|
|
|
|
.. image:: /_static/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:
|
|
|
|
.. image:: /_static/openapi_get_collections.png
|
|
|
|
The service collection metadata will contain a description of each collection:
|
|
|
|
.. image:: /_static/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:
|
|
|
|
.. image:: /_static/openapi_get_collection.png
|
|
|
|
.. image:: /_static/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:
|
|
|
|
.. image:: /_static/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``.
|
|
|
|
.. image:: /_static/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:
|
|
|
|
.. image:: /_static/openapi_get_item_id2.png
|
|
|
|
Using OpenAPI via ReDoc
|
|
-----------------------
|
|
|
|
pygeoapi also supports OpenAPI document rendering via `ReDoc <https://redocly.com/>`_.
|
|
|
|
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.
|