OpenAPI Challenges & Solutions (from Architecture DWG March 2022)

[jerstlouis]

Presented today to the Architecture DWG some challenges and solutions from OGC API - Tiles in defining re-usable OpenAPI buliding blocks for OGC API specifications, including consideration for generating pre-compiled generic clients.

• Re-using OpenAPI building blocks in OGC API definitions: paths, parameters, responses, and schemas
  • https://github.com/opengeospatial/ogcapi-tiles/tree/master/openapi
  • https://github.com/opengeospatial/ogcapi-tiles/blob/master/openapi/ogcapi-tiles-1.yaml
  • http://docs.ogc.org/DRAFTS/20-057.html#_reusable_api_components
• Listing path parameter values with JSON Schema enumerations facilitating direct re-use of an example OpenAPI definition
  • https://github.com/opengeospatial/ogcapi-tiles/tree/master/openapi/schemas/dynamic
• Taking this a step further and returning these enumerations dynamically
  • https://github.com/opengeospatial/ogcapi-tiles/tree/master/openapi/api
• Standardizing that capability so that OpenAPI definitions can be used to build pre-compiled generic clients
  • e.g. knowing that $ref: ../../api/all-collections.json will be available from the API at run-time, when using the OpenAPI definition to generate a compiled client
• Defining operationIDs suffixes for associating transportable resource paths with requirements conformance classes
  • http://docs.ogc.org/DRAFTS/20-057.html#_path_operation_ids
• OpenAPI's lack of templated path parameters – cannot enumerate based on context
  • Templated ref as a solution: $templatedRef: ../../api/styles/{collectionId}
  • Specifying dynamic resources enumerating valid values for a given path element OAI/OpenAPI-Specification#1693
  • Add support for templatedRef in Reference Object OAI/OpenAPI-Specification#2453
  • Parametrized/higher-order/templated schemas json-schema-org/json-schema-vocabularies#35
  • Dynamic schemas using templated "$ref" json-schema-org/json-schema-vocabularies#36

Presentation on the portal.

@ghobona @joanma747

[jerstlouis]

@joanma747 @cportele According to OAI/OpenAPI-Specification#2453 (comment) OAS 3.1 has this new $dynamicRef concept that may allow using templates in APIs for e.g., /collections/{collectionId}, /styles/{styleId}, /processes/{processId}, etc. at a particular end-point like https://maps.gnosis.earth/ogcapi/api/all-collections?f=json , https://maps.gnosis.earth/ogcapi/api/tileMatrixSets?f=json, etc.

Could that be right? I'm still intrigued by the possibility to auto-generate compiled clients from an API definition that will work with all implementations / deployments of an OGC API Standard.