From 161e1db7779aa33e9aee9a7171a28544a6464064 Mon Sep 17 00:00:00 2001 From: sethg Date: Fri, 10 Oct 2025 15:51:38 +0200 Subject: [PATCH 1/2] Add section on ows_extra_params for https://github.com/MapServer/MapServer/pull/7360 --- en/ogc/ogc_api.txt | 93 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 76 insertions(+), 17 deletions(-) diff --git a/en/ogc/ogc_api.txt b/en/ogc/ogc_api.txt index cb6bfa55f34..2ca41600c5d 100644 --- a/en/ogc/ogc_api.txt +++ b/en/ogc/ogc_api.txt @@ -9,7 +9,7 @@ :Author: Jeff McKenna :Contact: jmckenna at gatewaygeomatics.com -:Last Updated: 2025-09-11 +:Last Updated: 2025-10-10 .. contents:: Table of Contents :depth: 3 @@ -42,9 +42,9 @@ and the relevant emerging OGC API standards. .. table:: :align: left - + +------------+---------------------+ - | WxS | OGC API | + | WxS | OGC API | +============+=====================+ | OWS Common | OGC API - Common | +------------+---------------------+ @@ -58,7 +58,7 @@ and the relevant emerging OGC API standards. +------------+---------------------+ | SLD | OGC API - Styles | +------------+---------------------+ - + Requirements ============ @@ -360,17 +360,17 @@ Collections (JSON) or *ogcapi/collections?f=html* (HTML) such as:: http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/collections?f=html - + or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/collections?f=html`` - + .. image:: ../images/ogcapi-ms4w-collections.png :width: 400 :class: no-scaled-link - + .. TIP:: See a live MapServer 8.0 `OGCAPI: Features` collection at https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections?f=html - + Collection Items **************** @@ -380,11 +380,11 @@ Collection Items http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/collections/ + layername + /items?f=json or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/collections/lakes/items?f=json`` - + .. TIP:: Another clear reason to **never** use spaces or special characters in your mapfile's layer NAME parameter. - + .. image:: ../images/ogcapi-ms4w-collections-items-geojson.png :width: 400 :class: no-scaled-link @@ -392,18 +392,18 @@ Collection Items .. TIP:: See a live MapServer 8.0 `OGCAPI: Features` collection item (as GeoJSON) at https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections/lakes/items?f=json - + - you can access your OGC API collection items in HTML such as *ogcapi/collections/layername/items?f=html* such as:: http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/collections/ + layername + /items?f=html - + or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/collections/lakes/items?f=html`` .. image:: ../images/ogcapi-ms4w-collections-items-html.png :width: 400 :class: no-scaled-link - + .. TIP:: See a live MapServer 8.0 `OGCAPI: Features` collection item (in HTML) at https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections/lakes/items?f=html @@ -415,13 +415,13 @@ API Document (JSON) or *ogcapi/api?f=html* (HTML) such as:: http://127.0.0.1/cgi-bin/mapserv.exe/ + your mapfile alias + /ogcapi/api?f=json - + or in the above example, it would be: ``http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi/api?f=json`` - + .. image:: ../images/ogcapi-ms4w-api-json.png :width: 400 :class: no-scaled-link - + .. TIP:: See a live MapServer 8.0 `OGCAPI: Features` API document (in HTML) at https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/api?f=html @@ -444,11 +444,70 @@ Web Object Metadata **ows_schemas_location** .. versionadded:: 8.2.0 - + - *Description:* (Optional) (Note the name *ows_schemas_location* because all OGC Web Services (OWS) use the same metadata) Root of the web tree where the family of OGC API JSON Schema files are located. This must be a valid URL where the actual .yaml files are located if you want your OpenAPI description to be valid. Default is *http://schemas.opengis.net* +.. index:: + triple: OGCAPI; METADATA; ows_schemas_location + +**ows_extra_params** + + .. versionadded:: 8.4.0 + +- *Description:* (Optional) The ``ows_extra_params`` (or ``oga_extra_params``) metadata entry allows you to append + additional query parameters to all URLs generated by MapServer. This can be used, for example, + to include authentication tokens such as JSON Web Tokens (JWT) in your API requests. + + The value supports :ref:`Run-time Substitution `, where tokens in the form + ``%TOKEN%``, are replaced with validated values from the query string or cookies. + Parameters are validated against the rules in the :ref:`VALIDATION ` block. + ``ows_extra_params`` can also be set at the ``LAYER`` ``METADATA`` level, for adding or overriding parameters at the collection-level. + Example Mapfile: + + .. code-block:: mapfile + + WEB + VALIDATION + 'token' '^[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+$' + 'user_id' '^[0-9]+$' # only allow integers + 'default_token' 'MISSING' + 'default_user_id' '-1' + END + METADATA + "ows_extra_params" "token=%TOKEN%&user_id=%USER_ID%" + + Example URL:: + + http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=html&token=eyJ9.e30.SflKxw&user_id=938 + + Will return JSON containing the same parameters and values for all links: + + .. code-block:: json + + { + "description": "This is a demo OGC API server.", + "links": [ + { + "href": "http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=json&token=eyJ9.e30.SflKxw&user_id=938", + + If a parameter is missing or invalid, it is replaced by the corresponding default value (e.g., ``MISSING`` for token, ``-1`` for user_id). + Example URL:: + + http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=html&token=@@@@@&user_id=a03kf-9 + + Will return: + + .. code-block:: json + + { + "description": "This is a demo OGC API server.", + "links": [ + { + "href": "http://127.0.0.1/cgi-bin/mapserv.exe/localdemo/ogcapi?f=json&token=MISSING&user_id=-1", + The extra parameters are available in HTML templates for the OGC Features API as ``{{ template.extra_params }}``. + The templates supplied in the MapServer repository append this value to all URLs by default. From 507258d5304a0b4285f24fe17a423a5b18ad4d1d Mon Sep 17 00:00:00 2001 From: sethg Date: Sat, 11 Oct 2025 11:07:23 +0200 Subject: [PATCH 2/2] Add note re case-sensitivity --- en/ogc/ogc_api.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/ogc/ogc_api.txt b/en/ogc/ogc_api.txt index 2ca41600c5d..7e9cd64695c 100644 --- a/en/ogc/ogc_api.txt +++ b/en/ogc/ogc_api.txt @@ -464,7 +464,7 @@ Web Object Metadata The value supports :ref:`Run-time Substitution `, where tokens in the form ``%TOKEN%``, are replaced with validated values from the query string or cookies. - Parameters are validated against the rules in the :ref:`VALIDATION ` block. + Parameters are validated against the rules in the :ref:`VALIDATION ` block, and are case-insensitive. ``ows_extra_params`` can also be set at the ``LAYER`` ``METADATA`` level, for adding or overriding parameters at the collection-level. Example Mapfile: