TASC aids the harmonisation of aspects of GA4GH's various products that would otherwise prevent different products from being used together conveniently.
Service developers may choose to add implementation-specific properties to a GA4GH API. Or they may even choose to add additional endpoints (e.g., for POST, PUT, DELETE operations) that might make sense to host next to the existing endpoints at the same path.
To give clients the chance to discover and potentially be mindful of OpenAPI modifications, we could mandate or at least encourage the hosting of the actual OpenAPI specification at a well-known location, relative to the API.
A possible solution
Encourage or mandate the hosting of the actual (Open)API specfication for a given service instance, as a single source of truth, statically at path/to/api/specification, or - if we agree that such a feature should apply only to OpenAPI specifications - perhaps at a more descriptive location, such as path/to/api/openapi.json (see Additional Context below).
Given a URL to where the actual specification is hosted (or a base URL to which the client then applies any suffixes or rules described in the servers section of an OpenAPI specification to construct the path to the API), any client would then be able to obtain the definite version of the specification underlying any given service instance.
Note that this may actually drop the requirement for a given client to be coded against a specific version of an API altogether. A sufficiently "smart" client (if people chose to implement such a client - opinions may differ on whether that is useful or desirable) would not need to be tied to a specific API version, or even be aware of the specification beforehand at all, in order to interact with it.
Additional context
I would like to credit the excellent Connexion framework for the "modelless" implementation of "API first" services based on Python Flask (which is underlying almost all of the ELIXIR Cloud & AAI DP services) for inspiration here, as it is statically hosting the final compiled OpenAPI specification, including all modifications, at a configurable path - a feature which we have found useful for the reasons described above, and which we think would be even more useful if all implementers adhere to it (at least optionally).
uniqueg
commented
3 weeks ago
Problem statement
Service developers may choose to add implementation-specific properties to a GA4GH API. Or they may even choose to add additional endpoints (e.g., for
POST,PUT,DELETEoperations) that might make sense to host next to the existing endpoints at the same path.To give clients the chance to discover and potentially be mindful of OpenAPI modifications, we could mandate or at least encourage the hosting of the actual OpenAPI specification at a well-known location, relative to the API.
A possible solution
Encourage or mandate the hosting of the actual (Open)API specfication for a given service instance, as a single source of truth, statically at
path/to/api/specification, or - if we agree that such a feature should apply only to OpenAPI specifications - perhaps at a more descriptive location, such aspath/to/api/openapi.json(see Additional Context below).Given a URL to where the actual specification is hosted (or a base URL to which the client then applies any suffixes or rules described in the
serverssection of an OpenAPI specification to construct the path to the API), any client would then be able to obtain the definite version of the specification underlying any given service instance.Note that this may actually drop the requirement for a given client to be coded against a specific version of an API altogether. A sufficiently "smart" client (if people chose to implement such a client - opinions may differ on whether that is useful or desirable) would not need to be tied to a specific API version, or even be aware of the specification beforehand at all, in order to interact with it.
Additional context
I would like to credit the excellent Connexion framework for the "modelless" implementation of "API first" services based on Python Flask (which is underlying almost all of the ELIXIR Cloud & AAI DP services) for inspiration here, as it is statically hosting the final compiled OpenAPI specification, including all modifications, at a configurable path - a feature which we have found useful for the reasons described above, and which we think would be even more useful if all implementers adhere to it (at least optionally).
An example of a service for which the API is hosted is here: https://elixir-cloud.dcc.sib.swiss/ga4gh/registry/v1/ui. The API definition for that service, in JSON, is hosted here: https://elixir-cloud.dcc.sib.swiss/ga4gh/registry/v1/openapi.json