Designing and Implementing a Mechanism to Enable/Disable Optional/Non-Finalized Parts of the Specification

[aaime]

Quoting from geoserver-devel, @aaime mail:

The issue with OGC APIs development is that an implementation of a service is an amalgamation
of various small specs, all of which are in different stages of development, some stable, other subject
to change.
The issue becomes evident when this is coupled with Spring MVC controllers, e.g. the items resource:
in the same method signature we have bits that are finalized (bbox, limit, datetime), bit that are
only formally finalized (filter, filter-lang, filter-crs) and others that are coming straight out of other
specifications (sortby).

So, we'll have a need to separate OGC API Features so that the unstable bits are left out in the community, as
plugins, while the stable bits are found in the extension

But also from @jodygarnett :

My customers really want fine grain control over the conformances; the ability to enable/disable on a case-by-case basis

And again from @aaime :

That's an interesting challenge... we'd have to be able to selectively disable resources, resource methods, and resource query parameters/body elements (some API do use JSON document as POST, e.g. STAC API search endpoint). At the same time, they should behave like they are not implemented, so not denied, but ignored: we cannot go out with an error message because you're trying to use sort-by and it's been disabled, it should just be ignored as if the server did not implement it.

What does it mean to add a conformance class? It means acting on the following (not all mandatory):

• Advertising the conformance class URI in the API conformance declaration
• Advertise and describe itself in the OpenAPI document
  • New resources
  • New query parameters for resources
  • New properties in JSON documents (be it requests or responses)
  • New resource representations
• New resources
• New query parameters for resources
• New properties in JSON documents (be it requests or responses)
• New resource representations (Spring converters)

What do we have today in this area:

• To add new resources, just add a separate controller. Bonus points if annotated with APIService.
• DocumentCallback to add links and eventually other properties
• JSONAnyGetter/JSONAnySetter for random extra bits in documents (@jodygarnett suggests to call it "any").

The "conformance class" extension point needs to be flexible:

• Configurable so that it can be enabled and disabled (disabled means ignoring it, maybe with a response HTTP header to identify that the class is there but disabled. For representation formats however we have to return an error)
• Pluggable so that it can reside on a separate module (e.g. non finalized extensions subject to change, for example CRUD)

Another important aspect: how to store the configuration of enabled/disabled conformance classes?
Metadata map is an option.

Configuration of a conformance class:

• Simple enabled/disable
• Some might have their own customization (global for the conformance class)
• Some, like filtering, might have a per collection customization (e.g., queryables enumerate which attributes I can use to build filter)

[jodygarnett]

I probably should have waited until after the tour before embarking on this one. I decided to just get going mirroring the structure of service / service info with module / conformance.

Things I learned in initial attempt reviewing OWS:

• The OGCAPI talks in terms service modules, with each module listing a conformance URI documenting what it is capable of
• Service has a disconnected relationship with Operation, something similar may be appropriate between a Service and Modules
• Service Loaders in many cases are responsible for configuring a Service with Operations which is not what I would expect

Things I learned in initial attempt reviewing OGCAPI:

• I like the idea of a module storing its configuration SerivceInfo
• Straight forward to store in in metadataMap by conformance with a True/False to enable/disable, but a richer structure is possible.
• APIService annotation already has the idea of core true/false, which is close to the idea I had for module.

I am gradually steering towards having Service setup with several Modules, where the Modules retrieve their configuration from the ServiceInfo, and then decide if they are enabled/disabled appropriately.

[jodygarnett]

PR: geoserver/geoserver#8014

[aaime]

@jodygarnett the sprint work is blocked by this activity... we need a full implementation of it, including GUI and actual application of each conformance class in the code.