Adding CSAPI to an API - Features Implementation

[Sam-Bolling]

This is a general discussion on the topic of extending an existing OGC API - Features server implementation to include OGC API - Connected Systems. We started the topic in an email thread and Jan wisely recommended we migrate it over to a discussion for continued collaboration and transparency. I am pasting over Jan's initial notes here:

General Notes

• The schemas (https://opengeospatial.github.io/ogcapi-connected-systems/redoc/?url=../api/part1/openapi/openapi-connectedsystems-1.yaml#tag/Systems) are fine when using our own fork of redocly (which Alex Robin optimized for sensorML), but most OpenAPI Parsers cannot handle recursion and just break beyond repair (mostly because of bad programming). This might also affect some of the code-generation tools. Unfortunately this is an ingrained problem of SensorML which is by nature recursive.

• Once you have a single Entity (e.g. System) implemented, the others are basically just copy & paste.

• Whilst we support some "free text queries" (the q parameter), it is by far not enough to actually warrant complex "indexing" logic for text fields. I wasted too much time for a rather niche feature i didn't see in a single client yet.

• most endpoints support at least one mimetype/encodingtype, so we need to somehow transform them between encodings. A solution for this multi-encoding problem should probably be thought of early in development, it was quite a hassle to implement it after-the-fact. (The 52N-implementation currently works on the base of only accepting POSTing of sml+json and then internally converts it (on-push) into the "alternative" types. This works okay for simple entities, for complex ones this will probably break.)

• ignore the /collections endpoint at first, it is just a hassle and the full functionality is also available using other endpoints.

Some useful links:

• Bundles for the whole API (e.g. for serving as static openAPI document): https://github.com/52North/ogcapi-connected-systems/releases/tag/v1.0 (i just rebuilt them, was not able to fully test them yet)
• Single-File Bundles as json-schema for each entity. Useful for validation of request/response payloads. These might be slightly outdated, but should suffice for a first POC
  • https://github.com/52North/connected-systems-pygeoapi/tree/main/connected-systems-api/schemas (Generated by https://github.com/52North/connected-systems-pygeoapi/blob/main/tools/bundler/bundler.js)