Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Encourage/mandate hosting (Open)API specs at well-known location #43

Open
uniqueg opened this issue Feb 14, 2023 · 1 comment
Open

Encourage/mandate hosting (Open)API specs at well-known location #43

uniqueg opened this issue Feb 14, 2023 · 1 comment

Comments

@uniqueg
Copy link

uniqueg commented Feb 14, 2023

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, 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).

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant