[MapServer-dev] RFC-140 - MapServer Homepage
Seth G
sethg at geographika.co.uk
Thu Jul 3 01:29:43 PDT 2025
Hi devs,
I have been prototyping the MapServer Homepage, and the design has evolved since the initial RFC.
I've mocked up the JSON and HTML template outputs, using the same theme as the current MapServer OGC API. The API will be divided into two levels - a top-level landing page, and individual landing pages for each Mapfile. The JSON approach aims to be compatible with the IETF API Catalog specification.
1. Landing Page: https://geographika.github.io/mapserver-templates/ and https://geographika.github.io/mapserver-templates/api-catalog.json
I have just included the map file name and alias from the CONFIG file found at https://github.com/geographika/mapserver-templates/blob/main/mapfiles/mapserver.conf
Opening all Mapfiles for the landing page could become very slow with 100s of Mapfiles, but could be possible if we wanted to take a title rather than using a Mapfile filename.
2. Individual Mapfile Landing Pages: https://geographika.github.io/mapserver-templates/kitchensink/ and https://geographika.github.io/mapserver-templates/kitchensink/api-catalog.json
This will list all available services within the Mapfile. The "Kitchensink" demo has everything available - OGC Features, WMS, WFS, and WCS. Note as this is a mock-up the links don't actually return GetCapabilities files at the moment.
I have not yet included SOS (and possible CGI services). Again only minimal details are shown - adding data such as layers and extents seems redundant as a user can drill down into the GetCapabilities or OGC API Landing Page to get these details. A brief summary of the Mapfile (name, abstract etc.) could be included as metadata? We'd need to decide on precedence as these details could be configured differently for different services e.g. OGC Features API could use a different abstract than WMS.
Sample Mapfiles on which these services are based can be seen at https://github.com/geographika/mapserver-templates/tree/main/mapfiles
Please let me know your thoughts and comments on the above. If there are no objections to the changes I'll update the RFC and continue with development. I think "Landing Page" may be the best term to use, as this follows the OGC APIs terminology. As the design has changed from the initial RFC does this require a new vote?
Seth
--
web:https://geographika.net & https://mapserverstudio.net
mastodon: @geographika at mastodon.social
On Tue, Mar 18, 2025, at 1:18 AM, Daniel Morissette wrote:
> I like the idea of using PATH_INFO to control this, and "index" sounds
> like a good option as the default value as you suggested. I'm also fine
> with picking from the other names that were suggested.
>
>
>
> On 2025-03-13 06:22, Seth G wrote:
>> Thanks all for the votes and feedback.
>>
>> I'm not sure why I went with the ?mode=config&f=json approach - using
>> the URL path would be a better fit, as I'm trying to follow the OGC API
>> approach as much as possible. Allowing Mapfile references in the index
>> was added in [1].
>>
>> Daniel - I agree "config" could be confusing, and may be better used for
>> working with the CONFIG directly. I'm now no longer that keen on
>> "homepage" either! Maybe "index" would be a better fit, similar to the
>> root of a website defaulting to index.html.
>>
>> Alternatively, I've just been testing out allowing the homepage/index at
>> the root of MapServer, if the MS_HOMEPAGE_TEMPLATE_DIRECTORY is set. The
>> index would then be returned with an empty URL such as
>> http://localhost/mapserver/ <http://localhost/mapserver/>. This would
>> also avoid returning the "loadParams(): Web application error. No query
>> information to decode. QUERY_STRING is set, but empty. " message.
>>
>> [1] https://github.com/MapServer/MapServer/pull/6862 <https://
>> github.com/MapServer/MapServer/pull/6862>
>> --
>> web:https://geographika.net <https://geographika.net> & https://
>> mapserverstudio.net <https://mapserverstudio.net>
>> mastodon: @geographika at mastodon.social <mailto:geographika at mastodon.social>
>>
>> On Tue, Mar 11, 2025, at 5:46 PM, Lime, Steve D (MNIT) via MapServer-dev
>> wrote:
>>>
>>> The path after the binary name is available to you through an
>>> environment variable (PATH_INFO) as part of normal web server
>>> processing. We leverage that for OGC API support. In this case, you’d
>>> just look at the first component of the PATH_INFO and see if it
>>> matches your keyword (e.g. homepage) and then process accordingly (if
>>> enabled). Otherwise the first component of PATH_INFO is interpreted as
>>> the mapfile (more typically the mapfile alias) – Seth added that
>>> support in 8.2 (I think).
>>>
>>>
>>> *From:*Richard Greenwood <richard.greenwood at gmail.com>
>>> *Sent:* Tuesday, March 11, 2025 11:35 AM
>>> *To:* Lime, Steve D (MNIT) <steve.lime at state.mn.us>
>>> *Cc:* Daniel Morissette <dmorissette at mapgears.com>; mapserver-
>>> dev at lists.osgeo.org
>>> *Subject:* Re: [MapServer-dev] RFC-140 - MapServer Homepage
>>>
>>>
>>>
>>> On Tue, Mar 11, 2025 at 8:47 AM Lime, Steve D (MNIT) via MapServer-dev
>>> <mapserver-dev at lists.osgeo.org <mailto:mapserver-dev at lists.osgeo.org>>
>>> wrote:
>>>
>>> One idea might be to support a more restful URL, e.g. https://
>>> myhost.com/cgi-bin/mapserv/homepage <https://myhost.com/cgi-bin/
>>> mapserv/homepage> (or /home or /index or ?) instead of using a
>>> parameter-based approach. Maybe that endpoint name could be
>>> configurable via the config file – and that could also enable the
>>> functionality.
>>>
>>>
>>> Steve, correct me if I'm wrong, but that seems like it's getting into
>>> the realm of the web server. Like how is the mapserv binary to know
>>> that it should look for, and process, stuff after the "/"? What
>>> happens for example with "cgi-bin/mapserv.fcgi/homepage"? Does Apache
>>> know that I want to run the mapserv binary in fcgi mode and also know
>>> to pass the "homepage" part to the binary as a parameter? I like the
>>> idea of a restful syntax but I can't get my head around the
>>> implementation.
>>>
>>>
>>> Rich
>>>
>>>
>>>
>>> *From:*MapServer-dev <mapserver-dev-bounces at lists.osgeo.org
>>> <mailto:mapserver-dev-bounces at lists.osgeo.org>> *On Behalf Of
>>> *Daniel Morissette via MapServer-dev
>>> *Sent:* Monday, March 10, 2025 4:58 PM
>>> *To:* mapserver-dev at lists.osgeo.org <mailto:mapserver-
>>> dev at lists.osgeo.org>
>>> *Subject:* Re: [MapServer-dev] RFC-140 - MapServer Homepage
>>>
>>>
>>> Hi everyone,
>>>
>>>
>>> Sorry for being late with my feedback. I like the RFC overall,
>>> but was wondering if we could find a better trigger than
>>> mode=config for this feature. My first reaction when I saw
>>> mode=config was that this mode could be used to deal with the
>>> actual config settings in the future if we ever want to go there
>>> so using mode=config today for this homepage feature could limit
>>> our future options. That being said, I couldn't find any good
>>> names other than mode=homepage to match the
>>> MS_HOMEPAGE_TEMPLATE_DIRECTORY variable that controls it.
>>>
>>>
>>> I can live with mode=config if we have no better option and am +1
>>> with the RFC otherwise.
>>>
>>>
>>> Daniel
>>>
>>>
>>>
>>>
>>> On 2025-03-09 11:57, Seth G via MapServer-dev wrote:
>>>
>>> Hi all,
>>>
>>>
>>> I've added in the feedback from the comments above to RFC 140
>>> [1], see diff of changes at [2].
>>>
>>> I'd like to now formally propose to adopt this RFC, starting
>>> with my +1.
>>>
>>>
>>> Seth
>>>
>>>
>>> [1] https://mapserver.org/development/rfc/ms-rfc-140.html
>>> <https://mapserver.org/development/rfc/ms-rfc-140.html>
>>>
>>> [2] https://github.com/MapServer/MapServer-documentation/
>>> pull/1000/files <https://github.com/MapServer/MapServer-
>>> documentation/pull/1000/files>
>>>
>>>
>>> --
>>>
>>> web:https://geographika.net <https://geographika.net/> &
>>> https://mapserverstudio.net <https://mapserverstudio.net/>
>>>
>>> mastodon: @geographika at mastodon.social
>>> <mailto:geographika at mastodon.social>
>>>
>>>
>>> On Wed, Jan 22, 2025, at 4:40 PM, Tom Kralidis wrote:
>>>
>>> Thanks Seth.
>>>
>>>
>>> RE: service-meta: I would still keep to the link
>>> conventions (proper media type for "type", we could add a
>>> custom "service-type=WMS" property), and include an href
>>> as well.
>>>
>>>
>>> ..Tom
>>>
>>>
>>> On Wed, Jan 22, 2025 at 10:27 AM Seth G
>>> <sethg at geographika.co.uk <mailto:sethg at geographika.co.uk>>
>>> wrote:
>>>
>>>
>>> Thanks Tom - that pygeoapi pull request is good timing!
>>>
>>>
>>> After reviewing and reading some of the associated
>>> documents, I'm planning to update the RFC with the
>>> notes below.
>>>
>>>
>>> pygeoapi has implemented a JSON service for their
>>> homepage at [1] (pull request at [2].
>>>
>>> This implements the api-catalog, a draft IETF
>>> (Internet Engineering Task Force) standard [3].
>>>
>>> The Link Set format is described at [4]. It is
>>> proposed this approach is used to generate JSON for a
>>> MapServer "homepage".
>>>
>>> The generated JSON format can be seen at https://
>>> demo.pygeoapi.io/api-catalog.json <https://
>>> demo.pygeoapi.io/api-catalog.json>, with an extract below:
>>>
>>>
>>> {
>>>
>>> "linkset": [
>>>
>>> {
>>>
>>> "anchor": "https://demo.pygeoapi.io/master
>>> <https://demo.pygeoapi.io/master>",
>>>
>>> "service-desc": [
>>>
>>> {
>>>
>>> "href": "https://demo.pygeoapi.io/master/
>>> openapi?f=json <https://demo.pygeoapi.io/master/
>>> openapi?f=json>",
>>>
>>> "title": "pygeoapi - latest GitHub 'master'
>>> version (JSON)",
>>>
>>> "type": "application/vnd.oai.openapi+json"
>>>
>>> }
>>>
>>> ],
>>>
>>> "service-doc": [
>>>
>>> {
>>>
>>> "href": "https://demo.pygeoapi.io/master/
>>> openapi?f=html <https://demo.pygeoapi.io/master/
>>> openapi?f=html>",
>>>
>>> "title": "pygeoapi - latest GitHub 'master'
>>> version (HTML)",
>>>
>>> "type": "text/html"
>>>
>>> }
>>>
>>> ]
>>>
>>> },
>>>
>>>
>>> The spec allows for an additional "service-meta"
>>> property "used to link to additional metadata about
>>> the API,
>>>
>>> and is primarily intended for machine consumption." I
>>> think this can be used to add any additional
>>> properties from Mapfiles
>>>
>>> we'd need to generate a MapServer homepage.
>>>
>>> "service-doc" isn't mandatory, so WxS service links
>>> can ignore this. An example of the proposed JSON and
>>> metadata is shown below:
>>>
>>>
>>> {
>>>
>>> "linkset": [
>>>
>>> {
>>>
>>> "anchor": "https://demo.mapserver.org/ <https://
>>> demo.mapserver.org/>",
>>>
>>> "service-desc": [
>>>
>>> {
>>>
>>> "href": "https://demo.mapserver.org/cgi-bin/
>>> msautotest?
>>> SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities
>>> <https://demo.mapserver.org/cgi-bin/msautotest?
>>> SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities>",
>>>
>>> "title": "World WMS service",
>>>
>>> "type": "text/xml"
>>>
>>> }
>>>
>>> ],
>>>
>>> "service-meta": {
>>>
>>> {
>>>
>>> "type": "wms",
>>>
>>> "title": "WMS demo server for MapServer,
>>> used in the msautotest suite",
>>>
>>> "keywords": ["layers", "list"],
>>>
>>> "mapfile": "msautotest.map",
>>>
>>> }
>>>
>>> }
>>>
>>> },
>>>
>>>
>>> Seth
>>>
>>>
>>> [1] https://demo.pygeoapi.io/ <https://demo.pygeoapi.io/>
>>>
>>> [2] https://github.com/geopython/demo.pygeoapi.io/
>>> pull/60/files <https://github.com/geopython/
>>> demo.pygeoapi.io/pull/60/files>
>>>
>>> [3] https://datatracker.ietf.org/doc/draft-ietf-
>>> httpapi-api-catalog/08/ <https://datatracker.ietf.org/
>>> doc/draft-ietf-httpapi-api-catalog/08/>
>>>
>>> [4] https://www.rfc-editor.org/rfc/rfc9264.html
>>> <https://www.rfc-editor.org/rfc/rfc9264.html>
>>>
>>>
>>>
>>> --
>>>
>>> web:https://geographika.net <https://geographika.net/>
>>> & https://mapserverstudio.net <https://
>>> mapserverstudio.net/>
>>>
>>> mastodon: @geographika at mastodon.social
>>> <mailto:geographika at mastodon.social>
>>>
>>>
>>> On Sun, Jan 19, 2025, at 5:10 PM, Tom Kralidis wrote:
>>>
>>> Seth: thanks for this RFC. IETF has api-catalog
>>> (draft, [1]) which I think would be a good
>>> candidate for this RFC. This is also an item for
>>> review in the OGC API - Records SWG [2].
>>>
>>>
>>> Overall it looks pretty close to the RFC
>>> proposal. We can consider using api-catalog as a
>>> baseline and we can extend the JSON accordingly as
>>> needed for anything specific to our needs.
>>>
>>>
>>> Cheers
>>>
>>>
>>> ..Tom
>>>
>>>
>>> [1] https://datatracker.ietf.org/doc/draft-ietf-
>>> httpapi-api-catalog <https://datatracker.ietf.org/
>>> doc/draft-ietf-httpapi-api-catalog>
>>>
>>> [2] https://github.com/opengeospatial/ogcapi-
>>> records/issues/355 <https://github.com/
>>> opengeospatial/ogcapi-records/issues/355>
>>>
>>>
>>>
>>>
>>>
>>> On Sat, Jan 18, 2025 at 5:39 PM Seth G via
>>> MapServer-dev <mapserver-dev at lists.osgeo.org
>>> <mailto:mapserver-dev at lists.osgeo.org>> wrote:
>>>
>>> Looking again at the landing page JSON at
>>> https://demo.mapserver.org/cgi-bin/mapserv/
>>> localdemo/ogcapi?f=json <https://
>>> demo.mapserver.org/cgi-bin/mapserv/localdemo/
>>> ogcapi?f=json> it is in the same format, so as
>>> you suggested could simply be expanded with
>>> links to WxS services, or even CGI generated
>>> responses. This would also more easily allow
>>> template reuse.
>>>
>>>
>>> Seth
>>>
>>>
>>> --
>>>
>>> web:https://geographika.net <https://
>>> geographika.net/> & https://
>>> mapserverstudio.net <https://mapserverstudio.net/>
>>>
>>> mastodon: @geographika at mastodon.social
>>>
>>>
>>> On Sat, Jan 18, 2025, at 11:33 PM, Seth G via
>>> MapServer-dev wrote:
>>>
>>> > Hi Even,
>>>
>>> >
>>>
>>> > Thanks for your valuable feedback.
>>>
>>> >
>>>
>>> > The homepage would be a "superset" of all
>>> available Mapfiles in a
>>>
>>> > MapServer deployment, as listed in the
>>> CONFIG file. Each individual
>>>
>>> > Mapfile would still have its own OGC API
>>> landing page, so the homepage
>>>
>>> > is best described as a directory of all
>>> landing pages.
>>>
>>> >
>>>
>>> > As most MapServer deployments will likely be
>>> serving out a combination
>>>
>>> > of WxS and new OGC API services for some
>>> time to come, it will allow
>>>
>>> > both types to be listed together (I'm
>>> unaware of a OGC API spec that
>>>
>>> > would cover this).
>>>
>>> >
>>>
>>> > In regard to the JSON used for links, I was
>>> modelling it as closely as
>>>
>>> > possible to OGC API conventions. Looking at
>>> the pygeoapi demo home
>>>
>>> > page, it provides a set of links in a common
>>> format, so I'll likely
>>>
>>> > switch to this format/approach:
>>>
>>> >
>>>
>>> > https://demo.pygeoapi.io/stable?f=json
>>> <https://demo.pygeoapi.io/stable?f=json>
>>>
>>> >
>>>
>>> > A few of the "rel" values are defined as
>>> below, and can be reused:
>>>
>>> >
>>>
>>> > alternate Provides an alternate
>>> representation (e.g., HTML version of a
>>>
>>> > resource).
>>>
>>> > service-desc Links to the machine-readable
>>> API description (e.g.,
>>>
>>> > OpenAPI JSON).
>>>
>>> > service-doc Links to the human-readable
>>> API documentation (e.g.,
>>>
>>> > OpenAPI HTML).
>>>
>>> > conformance Lists the standards and
>>> conformance classes supported by
>>>
>>> > the API.
>>>
>>> >
>>>
>>> > I'll update the RFC with the above,
>>>
>>> >
>>>
>>> > Seth
>>>
>>> >
>>>
>>> > --
>>>
>>> > web:https://geographika.net <https://
>>> geographika.net/> & https://
>>> mapserverstudio.net <https://mapserverstudio.net/>
>>>
>>> > mastodon: @geographika at mastodon.social
>>>
>>> >
>>>
>>> > On Sat, Jan 18, 2025, at 12:39 PM, Even
>>> Rouault wrote:
>>>
>>> >> Seth,
>>>
>>> >>
>>>
>>> >> Thanks for putting this together. I'm
>>> wondering how much your proposal
>>>
>>> >> relates/intersects with the concept of the
>>> landing page of OGC API
>>>
>>> >> services ? You mention some connection with
>>> it, but it is not
>>>
>>> >> immediately clear to me the exact nature
>>> of the connection. Perhaps it
>>>
>>> >> is just a matter of clarifying. I have put
>>> zero thoughts in it, but it
>>>
>>> >> would feel weird to invent a MapServer
>>> specific thing, so I'm naively
>>>
>>> >> wondering if we can't we just adopt the
>>> landing page formalism (for the
>>>
>>> >> JSON part), and potentially extend it by
>>> exposing old WxS services as
>>>
>>> >> well in the links as you suggest? I'm also
>>> wondering if there's some
>>>
>>> >> best practice used by other projects on how
>>> to expose for things like
>>>
>>> >>
>>>
>>> >> {
>>>
>>> >> "href":
>>>
>>> >> "https://demo.mapserver.org/cgi-bin/wms?
>>> SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities <https://demo.mapserver.org/cgi-bin/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities>",
>>>
>>> >> "title": "GetCapabilities",
>>>
>>> >> "type": "WMS"
>>>
>>> >> },
>>>
>>> >>
>>>
>>> >> so they can be interoperably consumed.
>>>
>>> >>
>>>
>>> >> Even
>>>
>>> >>
>>>
>>> >> Le 18/01/2025 à 09:11, Seth G via
>>> MapServer-dev a écrit :
>>>
>>> >>> Hi devs,
>>>
>>> >>>
>>>
>>> >>> I've drafted an RFC with an approach of
>>> creating a MapServer homepage based on the
>>> MAPs referenced in a mapserver.conf file. This
>>> will allow MapServer installations to easily
>>> advertise available services, dynamically.
>>>
>>> >>>
>>>
>>> >>> Text available in pull request at https://
>>> github.com/MapServer/MapServer-documentation/
>>> pull/996 <https://github.com/MapServer/
>>> MapServer-documentation/pull/996>
>>>
>>> >>>
>>>
>>> >>> Comments and thoughts appreciated,
>>>
>>> >>> Thanks,
>>>
>>> >>>
>>>
>>> >>> Seth
>>>
>>> >>>
>>>
>>> >>> --
>>>
>>> >>> web:https://geographika.net <https://
>>> geographika.net/> & https://
>>> mapserverstudio.net <https://mapserverstudio.net/>
>>>
>>> >>> mastodon: @geographika at mastodon.social
>>>
>>> >>>
>>> _______________________________________________
>>>
>>> >>> MapServer-dev mailing list
>>>
>>> >>> MapServer-dev at lists.osgeo.org
>>> <mailto:MapServer-dev at lists.osgeo.org>
>>>
>>> >>> https://lists.osgeo.org/mailman/listinfo/
>>> mapserver-dev <https://lists.osgeo.org/
>>> mailman/listinfo/mapserver-dev>
>>>
>>> >>
>>>
>>> >> --
>>>
>>> >> http://www.spatialys.com <http://
>>> www.spatialys.com/>
>>>
>>> >> My software is free, but my time generally not.
>>>
>>> >> Butcher of all kinds of standards, open or
>>> closed formats. At the end,
>>>
>>> >> this is just about bytes.
>>>
>>> > _______________________________________________
>>>
>>> > MapServer-dev mailing list
>>>
>>> > MapServer-dev at lists.osgeo.org
>>> <mailto:MapServer-dev at lists.osgeo.org>
>>>
>>> > https://lists.osgeo.org/mailman/listinfo/
>>> mapserver-dev <https://lists.osgeo.org/
>>> mailman/listinfo/mapserver-dev>
>>>
>>> _______________________________________________
>>>
>>> MapServer-dev mailing list
>>>
>>> MapServer-dev at lists.osgeo.org
>>> <mailto:MapServer-dev at lists.osgeo.org>
>>>
>>> https://lists.osgeo.org/mailman/listinfo/
>>> mapserver-dev <https://lists.osgeo.org/
>>> mailman/listinfo/mapserver-dev>
>>>
>>>
>>>
>>>
>>> _______________________________________________
>>>
>>> MapServer-dev mailing list
>>>
>>> MapServer-dev at lists.osgeo.org <mailto:MapServer-dev at lists.osgeo.org>
>>>
>>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev <https://lists.osgeo.org/mailman/listinfo/mapserver-dev>
>>>
>>>
>>> --
>>>
>>> Daniel Morissette
>>>
>>> Mapgears Inc
>>>
>>> T: +1 418-696-5056 #201
>>>
>>> _______________________________________________
>>> MapServer-dev mailing list
>>> MapServer-dev at lists.osgeo.org <mailto:MapServer-dev at lists.osgeo.org>
>>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev <https://
>>> lists.osgeo.org/mailman/listinfo/mapserver-dev>
>>>
>>>
>>>
>>> --
>>>
>>> Richard W. Greenwood
>>> www.greenwoodmap.com <http://www.greenwoodmap.com/>
>>>
>>> _______________________________________________
>>> MapServer-dev mailing list
>>> MapServer-dev at lists.osgeo.org <mailto:MapServer-dev at lists.osgeo.org>
>>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev <https://
>>> lists.osgeo.org/mailman/listinfo/mapserver-dev>
>>>
>>
>
>
> --
> Daniel Morissette
> Mapgears Inc
> T: +1 418-696-5056 #201
More information about the MapServer-dev
mailing list