Openapi-specification: Support discovering OpenAPI document from `Link` header?

[evankanderson]

I'm looking at various options to "upgrade" a simple API (HTTP POST of CloudEvents) to allow clients and servers to be able to extend into more complex OpenAPI space (e.g. "what events are you interested in" or "what types of events might be returned in the HTTP response").

One attractive option would be to provide a Link header pointing to the OpenAPI spec on the existing endpoint to provide a hint that upgrade is available.

I don't see a documented rel (relation) value for OpenAPI; would something like "oas-3.0" be a reasonable value?

[MikeRalphson]

I think more generically service-desc might suit the bill. See https://tools.ietf.org/html/rfc8631

See #1511 #724 #734 for previous discussions including describedBy, and #110 for a proposed media-type for OAS documents.

[evankanderson]

service-desc looks like it fits the bill, thanks!

Any chance that this usage pattern could be documented better? A search for openapi link "service-desc" brings up #724 and then some usage from the opengeospatial project.

If it's useful, I can try to figure out where to add appropriate documentation?

[MikeRalphson]

When #110 (@darrelmiller) is resolved we would definitely look at an updated version of #734 wording, either in the spec. or in a guidance / technical note document.

[larsgsvensson]

+1 to using Link header. You might also consider to register a .well-known URI, which could make the description available at example.org/.well-known/openapi.

[MikeRalphson]

I recall @darrelmiller had some objection to using a .well-known URI for this case - could we document it here? It may have been that an OpenAPI document doesn't meet the criteria of

the discovery of information about an origin ... (sometimes called "site-wide metadata")

Of course one issue it doesn't cater for is an organisation having many APIs (which could be handled by something like apis.json). There is also the schema.org WebAPI type in this discovery space.