Skip to content

Add section on ows_extra_params #1044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 17, 2025
Merged

Add section on ows_extra_params #1044

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
161e1db
Add section on ows_extra_params for https://github.com/MapServer/MapS…
geographika Oct 10, 2025
507258d
Add note re case-sensitivity
geographika Oct 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 76 additions & 17 deletions en/ogc/ogc_api.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 |
+------------+---------------------+
Expand All @@ -58,7 +58,7 @@ and the relevant emerging OGC API standards.
+------------+---------------------+
| SLD | OGC API - Styles |
+------------+---------------------+

Requirements
============

Expand Down Expand Up @@ -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
****************

Expand All @@ -380,30 +380,30 @@ 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

.. 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
Expand All @@ -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
Expand All @@ -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 <runsub>`, 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 <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.