Skip to content

GSIP 230

Jump to bottom
Kevin Smith edited this page Jan 13, 2025 · 28 revisions

GSIP-230 OGC API Features Extension

Overview

This proposal recommends the OGCAPI Features community module to graduate to extension status.

Proposed By

Andrea, Gabe, and Jody.

Assigned to Release

This proposal is for GeoServer 2.27.

State

  • Under Discussion
  • In Progress
  • Completed
  • Rejected
  • Deferred

Motivation

With the OGC API Features standard approved, and the recent availability of CQL2 the web service is now suitable for general use.

Proposal

Extension status requirements

The developers guide lists several requirements for community modules graduating to an extension:

  1. The module has at least a “handful” of users

    • GeoCat has included this community module in GeoCat Map and GeoCat Live products.
    • GeoSolutions has several deployments using OGC APIs
    • Camptocamp's customers provided funding for the code sprint towards graduating ogcapi-features to extension status

  2. The module has a designated and active maintainer

    • Andrea Aime
    • Jody Garnett (GeoCat) is willing to act in this capacity
    • Gabriel Roldan

    The communication burden of a new categories of services will be intensive during the transition to OGCAPI services. The functionality of this module, and the integration of OGCAPI services with the GeoServer codebase, should be a goal for all GeoServer developers.

  3. The module is considered “stable” by the majority of the PSC.

    • OGC API Features is approved.
    • CQL2 is now approved
    • The ogcapi-core has several deep integrations with spring-framework that may be vulnerable to change. This is a caution to be aware of and acknowledge.

  4. The module maintains 40% test coverage

    • ogcapi-core coverage: 60%
    • ogcapi-features coverage: 89%

  5. The module has no IP violations

    • ogcapi-core reuses under a hundred lines of spring-framework code, correctly attributed via Apache License.
    • ogcapi-features contributors are all covered by OSGeo CLA

  6. The module has a page in the user manual

  7. The maintainer has signed the GeoServer Contributor Agreement

    • Andrea Aime covered under GeoSolutions CLA, registered with OSGeo secretary
    • Jody Garnett covered under GeoCat CLA, registered with OSGeo secretary
    • Gabriel Roldan covered by Camptocamp CLA, registered with OSGeo secretary

OGC API Core

Supports the creation of OGCAPI web services and integration with GeoServer Dispatcher.

  • @APIService annotation used to mark OGCAPI Services.

  • Services are implemented with normal spring-framework @GetMapping for REST API resources.

    Resources are defined with the help of useful base classes:

    • AbstractDocument: provides links
    • AbstractLandingPageDocumentNoConformance: Landing page used as model for json Jackson output, and with @HTMLResponseBody annotation for Freemarker html output
    • OpenAPI: OpenAPI specification document

    The result is a service definition as Java objects:

    ---
title: ogcapi-features
---
classDiagram
    class FeatureService {
        getLandingPage() FeaturesLandingPage
        api() OpenAPI
        getCollections() CollectionsDocument
        collection() CollectionDocument
    }
    Loading

  • APIDispatcher: OGCAPI Services are mapped to Dispatcher friendly Service and Operations subject to the security, control flow, and monitoring.

    ---
title: ogcapi-core
---
classDiagram
    class APIDispatcher {
        List callbacks
        List documentCallbacks
        List apiCallbacks
        List messageConverters
        initApplicationContext(context)
        handleRequestInternal(httpRequest,httpResponse) 
    }
    Loading

  • APIConformance: Represent optional functionality to reflect modular nature of OGCAPI Services. This is similar to WFS Service Level which selectively enables/disables the WFS Transaction operation.

Supports the configuration of service modules integrated with GeoServer Catalog:

  • OGCAPI Services make use of existing ServiceInfo configuration, when working with the same content.
  • OGCAPI Services may create their own SerivceInfo when introducing a new type of content.
  • Addition of beans for ServiceInfo metadata map, to enable/disable and configure APIConformance and any other service settings.

OGC API Features

This extension is additive in nature and does not affect the existing Open Web Services.

  • FeatureService reuses the WFSServiceInfo configuration, in effect providing an additional protocol to operate alongside WFS 1.0, WFS 1.1 and WFS 2.0.

  • To support the configuration of conformances WFSServiceInfo metadata model is used:

    • FeatureConformance - provides configuration for core service
    • CQL2Conformance - selectively enabled/disable CQL2 Text and CQL JSON options
    • ECQLConformance -

  • Functionality that is not considered stable is marked by an APIConformance DRAFT_STANDARD and is not enabled by default

  • Functionality that is not official is a COMMUNTY_STANDARD and is not enabled if WFS is strict

  • FeatureServiceAdminPanel provides a AdminPagePanel contribution to the WFS Service user interface for configuration.

    In the picture below GML3 support is on by default (as a STANDARD) but can be turned off by using the checkbox.

    image

Developers Guide

Add a section to the Programmers Guide describing ogcapi-core infrastructure interaction, leaving the details to javadocs.

This will be done when the proposal is approved.

A section to the CITE Test Guide has been added with instructions to build the required artifacts and run ogcapi-features CITE tests locally and for debugging purposes.

CITE Tests automation

A Continuous Integration github actions workflow has been added to run the CITE tests on each pull request.

Additionally, the workflow has been enabled also to run the CITE tests for other services.

image

User Guide

The existing documentation to be refactored when proposal approved:

  • Add a page to Services for OGCAPI Features.

  • Add any general background detail, such as configuration of freemarker templates, to Server configuration to avoid repeating the same content for each service.

Backwards Compatibility

Backwards compatibility:

  • OGC API Core: additive in nature extending the abilities of the GeoServer Dispatcher, and has no effect on backwards compatibility.
  • OGC API Features: Extension is additive in nature with no effect on backwards compatibility.

Default Behaviour:

  • OGCAPI Features is enabled by default (and may not presently be disabled)
  • APIConformance for stable functionality are enabled by default.
  • When in strict mode only official standards are enabled, while community standards are disabled.
  • APIConformance draft / experimental functionality are disabled by default.

The net effect is installing OGCAPI Features the service will pass CITE tests out of the box.

Configured behavior:

  • Service modules enabled/disabled status remains unchanged.
  • When a standard is approved and finalized it will be noted in the release announcement only.

When upgrading we wish to avoid providing new functionality with out admin approval.

Feedback

Q: Can you make a cut down GeoServer that only includes OGCAPI Features?

Yes, although it would not be much smaller in size.

Q: If I disable WFS will OGCAPI Features be disabled?

Yes, this is a feature not a bug.

It would be ideal to enable/disable WFS 1.0.0, WFS 1.1.1 and WFS 2.0.0 using ServiceModule.

Voting

Project Steering Committee:

  • Alessio Fabiani: +1
  • Andrea Aime: +1
  • Ian Turton: +1
  • Jody Garnett: +1
  • Jukka Rahkonen: +1
  • Kevin Smith: +1
  • Simone Giannecchini: +1
  • Torben Barsballe: +1
  • Nuno Oliveira: +1
  • Peter Smythe: +1

Links

©2022 Open Source Geospatial Foundation

Home
Proposals
Release Schedule
Maintenance & Roadmap
Sponsor

Clone this wiki locally