[MapServer-dev] Handling additional parameters in OGC Features API URLs

[Rahkonen Jukka]

Hi Seth,

The OGC API Features standard has also some considerations about vendor parameters https://docs.ogc.org/is/17-069r4/17-069r4.html#query_parameters. I do not know how to interpret the standard in this context but I believe that it limits how much we can fiddle with the request URLs. I recommend reading the whole paragraph but here is an excerpt:

7.6. Unknown or invalid query parameters
Requirement 8
/req/core/query-param-unknown

A
The server SHALL respond with a response with the status code 400, if the request URI includes a query parameter that is not specified in the API definition.
If a server wants to support vendor specific parameters, these have to be explicitly declared in the API definition.
If OpenAPI is used to represent the API definition, a capability exists to allow additional parameters without explicitly declaring them. That is, parameters that have not been explicitly specified in the API definition for the operation will be ignored.
OpenAPI schema for additional "free-form" query parameters
in: query
name: vendorSpecificParameters
schema:
  type: object
  additionalProperties: true
style: form

-Jukka Rahkonen-

________________________________________
Lähettäjä: MapServer-dev  käyttäjän Seth G via MapServer-dev  puolesta
Lähetetty: Tiistai 30. syyskuuta 2025 12.31
Vastaanottaja: MapServer Devs
Aihe: [MapServer-dev] Handling additional parameters in OGC Features API URLs


Hi devs,

We've been discussing at the OSGeo codesprint how to handle extra parameters when working with the OGC Features API. The issue is that additional parameters, such as a security token, are not persisted to the URLs constructed by MapServer. For example, a user might request:

https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections/?f=json&token=98127319283

However, MapServer will return a JSON response with URLs like:

"links": [
    {"href": "https://demo.mapserver.org/cgi-bin/mapserv/localdemo/ogcapi/collections/ocean?f=json"}
]

Client applications can append extra parameters with every request, but this is not always possible, for example when using ArcGIS Pro or QGIS.

MapServer already supports adding parameters for WxS services using Runtime Substitution, since all WEB METADATA values can accept parameters. For example, the ows_onlineresource returned in a GetCapabilities response can include URLs with tokens:

"ows_onlineresource" "http://my.host.com/cgi-bin/mapserv?map=/path/to/your-mapfile.map&%25TOKEN%25"

OGC Features URLs, however, are constructed in code by building paths and then appending querystring parameters, so runtime substitution cannot be used here. While HTML templates can be modified to include additional parameters, this does not affect URLs returned in f=json responses and updating all templates is time-consuming:

{"href", api_root + "/collections/" + std::string(id_encoded) + "?f=json"}

A proposed solution is to add a new METADATA item to allow extra parameters to be appended to these URLs:

"ows_extraparams" "token=%TOKEN%&userid=%USER_ID%"

- This would use the same Runtime Substitution approach as other METADATA items.
- Mapfile authors would be responsible for adding VALIDATION blocks for the parameters.
- All URL construction in mapogcapi.cpp would be updated to append extra_parameters to the end of URLs, handling edge cases such as ending ampersands or empty strings:
{"href", api_root + "/collections/" + std::string(id_encoded) + "?f=json" + extra_parameters}

As with other METADATA items, LAYER-level metadata would take precedence over WEB-level metadata. This would allow collection-level parameters to be supported when required.

Thoughts / comments welcome,

Seth

--
web:https://geographika.net/ & https://mapserverstudio.net/
mastodon: @geographika at mastodon.social
_______________________________________________
MapServer-dev mailing list
MapServer-dev at lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/mapserver-dev