.. _`ogc_api_features`: OGC API Features ============================================== OGC API Features (OAPIF) is the first implementation of the new generation of OGC protocols. It is described by the `OGC API - Features - Part 1: Core `_ document. Here is a quick informal summary of the most important differences between the well known WFS protocol and OAPIF: - OAPIF is based on a `REST `_ API - OAPIF must follow the `OPENAPI `_ specifications - OAPIF supports multiple output formats but it does not dictate any (only GeoJSON and HTML are currently available in QGIS OAPIF) and it uses `content negotiation `_ to determine which format is to be served to the client - JSON and HTML are first class citizens in OAPIF - OAPIF is self-documenting (through the ``/api`` endpoint) - OAPIF is fully navigable (through links) and browsable .. important:: While the OGC API Features implementation in QGIS can make use of the ``MAP`` parameter to specify the project file, no extra query parameters are allowed by the OPENAPI specification. For this reason it is strongly recommended that ``MAP`` is not exposed in the URL and the project file is specified in the environment by other means (i.e. setting ``QGIS_PROJECT_FILE`` in the environment through a web server rewrite rule). .. note:: The **API** endpoint provides comprehensive documentation of all supported parameters and output formats of your service. The following paragraphs will only describe the most important ones. Resource representation ----------------------- The implementation of OGC API Features in QGIS Server currently supports the following resource representation (output) formats: - HTML - JSON The format that is actually served will depend on content negotiation, but a specific format can be explicitly requested by appending a format specifier to the endpoints. Supported format specifier extensions are: - ``.json`` - ``.html`` Additional format specifier aliases may be defined by specific endpoints: - ``.openapi``: alias for ``.json`` supported by the **API** endpoint - ``.geojson``: alias for ``.json`` supported by the **Features** and **Feature** endpoints .. _oapif_endpoints: Endpoints -------------------- The API provides a list of endpoints that the clients can retrieve. The system is designed in such a way that every response provides a set of links to navigate through all the provided resources. Endpoints points provided by the QGIS implementation are: .. csv-table:: :header: "Name", "Path", "Description" :widths: auto "Landing Page", "``/``", "General information about the service and provides links to all available endpoints" "Conformance", "``/conformance``", "Information about the conformance of the service to the standards" "API", "``/api``", "Full description of the endpoints provided by the service and the returned documents structure" "Collections", "``/collections``", "List of all collections (i.e. 'vector layers') provided by the service" "Collection", "``/collections/{collectionId}``", "Information about a collection (name, metadata, extent etc.)" "Features", "``/collections/{collectionId}/items``", "List of the features provided by the collection" "Feature", "``/collections/{collectionId}/items/{featureId}``", "Information about a single feature" Landing Page ^^^^^^^^^^^^^^^^^^^^ The main endpoint is the **Landing Page**. From that page it is possible to navigate to all the available service endpoints. The **Landing Page** must provide links to - the API definition (path ``/api`` link relations ``service-desc`` and ``service-doc``), - the Conformance declaration (path ``/conformance``, link relation ``conformance``), and - the Collections (path ``/collections``, link relation ``data``). .. _figure_server_oapif_landing_page: .. figure:: ../img/server_wfs3_landing_page.png :align: center Server OAPIF landing page .. _`ogc_api_features_api_definition`: API Definition ^^^^^^^^^^^^^^^^^^^^ The **API Definition** is an OPENAPI-compliant description of the API provided by the service. In its HTML representation it is a browsable page where all the endpoints and their response formats are accurately listed and documented. The path of this endpoint is ``/api``. The API definition provides a comprehensive and authoritative documentation of the service, including all supported parameters and returned formats. .. note:: This endpoint is analogue to WFS's ``GetCapabilities`` Collections list ^^^^^^^^^^^^^^^^^^^^ The collections endpoint provides a list of all the collections available in the service. Since the service "serves" a single QGIS project the collections are the vector layers from the current project (if they were published as WFS in the project properties). The path of this endpoint is ``/collections/``. .. _figure_server_oapif_collections: .. figure:: ../img/server_wfs3_collections.png :align: center Server OAPIF collections list page Collection detail ^^^^^^^^^^^^^^^^^^^^^ While the collections endpoint does not provide detailed information about each available collection, that information is available in the ``/collections/{collectionId}`` endpoints. Typical information includes the extent, a description, CRSs and other metadata. The HTML representation also provides a browsable map with the available features. .. _figure_server_oapif_collection: .. figure:: ../img/server_wfs3_collection.png :align: center Server OAPIF collection detail page .. _`ogc_api_features_features_list`: Features list ^^^^^^^^^^^^^^^^^^^^^ This endpoint provides a list of all features in a collection knowing the collection ID. The path of this endpoint is ``/collections/{collectionId}/items``. The HTML representation also provides a browsable map with the available features. .. note:: This endpoint is analogue to ``GetFeature`` in WFS 1 and WFS 2. .. _figure_server_oapif_features: .. figure:: ../img/server_wfs3_features.png :align: center Server OAPIF features list page Feature detail ^^^^^^^^^^^^^^^^^^^^^^^ This endpoint provides all the available information about a single feature, including the feature attributes and its geometry. The path of this endpoint is ``/collections/{collectionId}/items/{itemId}``. The HTML representation also provides a browsable map with the feature geometry. .. _figure_server_oapif_feature: .. figure:: ../img/server_wfs3_feature.png :align: center Server OAPIF feature detail page Pagination -------------------- Pagination of a long list of features is implemented in the OGC API through ``next`` and ``prev`` links, QGIS server constructs these links by appending ``limit`` and ``offset`` as query string parameters. URL example: .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?offset=10&limit=10 .. note:: The maximum acceptable value for ``limit`` can be configured with the ``QGIS_SERVER_API_WFS3_MAX_LIMIT`` server configuration setting (see: :ref:`qgis-server-envvar`). Feature filtering -------------------- The features available in a collection can be filtered/searched by specifying one or more filters. Date and time filter ^^^^^^^^^^^^^^^^^^^^ Collections with date and/or datetime attributes can be filtered by specifying a ``datetime`` argument in the query string. By default the first date/datetime field is used for filtering. This behavior can be configured by setting a "Date" or "Time" dimension in the :menuselection:`QGIS Server --> Dimension` section of the layer properties dialog. The date and time filtering syntax is fully described in the :ref:`ogc_api_features_api_definition` and also supports ranges (begin and end values are included) in addition to single values. URL examples: Returns only the features with date dimension matching ``2019-01-01`` .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?datetime=2019-01-01 Returns only the features with datetime dimension matching ``2019-01-01T01:01:01`` .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?datetime=2019-01-01T01:01:01 Returns only the features with datetime dimension in the range ``2019-01-01T01:01:01`` - ``2019-01-01T12:00:00`` .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?datetime=2019-01-01T01:01:01/2019-01-01T12:00:00 Bounding box filter ^^^^^^^^^^^^^^^^^^^^ A bounding box spatial filter can be specified with the ``bbox`` parameter: The order of the comma separated elements is: - Lower left corner, WGS 84 longitude - Lower left corner, WGS 84 latitude - Upper right corner, WGS 84 longitude - Upper right corner, WGS 84 latitude .. note:: The OGC specifications also allow a 6 item bbox specifier where the third and sixth items are the Z components, this is not yet supported by QGIS server. URL example: .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?bbox=-180,-90,180,90 If the *CRS* of the bounding box is not `WGS 84 `_, a different CRS can be specified by using the optional parameter ``bbox-crs``. The CRS format identifier must be in the `OGC URI `_ format: URL example: .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?bbox=913191,5606014,913234,5606029&bbox-crs=http://www.opengis.net/def/crs/EPSG/9.6.2/3857 Attribute filters ^^^^^^^^^^^^^^^^^^^^ Attribute filters can be combined with the bounding box filter and they are in the general form: ``=``. Multiple filters can be combined using the ``AND`` operator. URL example: filters all features where attribute ``name`` equals "my value" .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?attribute_one=my%20value Partial matches are also supported by using a ``*`` ("star") operator: URL example: filters all features where attribute ``name`` ends with "value" .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?attribute_one=*value Feature sorting --------------- It is possible to order the result set by field value using the ``sortby`` query parameter. The results are sorted in ascending order by default. To sort the results in descending order, a boolean flag (``sortdesc``) can be set: .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?sortby=name&sortdesc=1 Attribute selection ------------------- The feature attributes returned by a :ref:`ogc_api_features_features_list` call can be limited by adding a comma separated list of attribute names in the optional ``properties`` query string argument. URL example: returns only the ``name`` attribute .. code-block:: bash http://localhost/qgisserver/oapif/collection_one/items.json?properties=name Customize the HTML pages ------------------------ The HTML representation uses a set of HTML templates to generate the response. The template is parsed by a template engine called `inja `_. The templates can be customized by overriding them (see: :ref:`server_oapif_template_override`). The template has access to the same data that are available to the ``JSON`` representation and a few additional functions are available to the template: Custom template functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``path_append( path )``: appends a directory path to the current url - ``path_chomp( n )``: removes the specified number "n" of directory components from the current url path - ``json_dump( )``: prints the JSON data passed to the template - ``static( path )``: returns the full URL to the specified static path. For example: "static( "/style/black.css" )" with a root path "http://localhost/qgisserver/oapif" will return "http://localhost/qgisserver/oapif/static/style/black.css". - ``links_filter( links, key, value )``: Returns filtered links from a link list - ``content_type_name( content_type )``: Returns a short name from a content type, for example "text/html" will return "HTML" - ``nl2br( text )``: Returns the input text with all newlines replaced by "
" tags .. _`server_oapif_template_override`: Template overrides ^^^^^^^^^^^^^^^^^^^^^^^^^^ Templates and static assets are stored in subdirectories of the QGIS server default API resource directory (:file:`/usr/share/qgis/resources/server/api/` on a Linux system), the base directory can be customized by changing the environment variable ``QGIS_SERVER_API_RESOURCES_DIRECTORY``. A typical Linux installation will have the following directory tree: .. code-block:: bash /usr/share/qgis/resources/server/api/ └── ogc ├── schema.json ├── static │   ├── jsonFormatter.min.css │   ├── jsonFormatter.min.js │   └── style.css └── templates └── wfs3 ├── describeCollection.html ├── describeCollections.html ├── footer.html ├── getApiDescription.html ├── getFeature.html ├── getFeatures.html ├── getLandingPage.html ├── getRequirementClasses.html ├── header.html ├── leaflet_map.html └── links.html To override the templates you can copy the whole tree to another location and point ``QGIS_SERVER_API_RESOURCES_DIRECTORY`` to the new location.