search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
29.11k stars 9.08k forks source link

Support discovering OpenAPI document from `Link` header? #2128

Open evankanderson opened 4 years ago

evankanderson commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

+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 commented 4 years ago

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.

POnakS commented 2 years ago

I think using Link is bad idea, as it assumes we're serving some kind of HTML. Which is not always the case.

evankanderson commented 2 years ago

This is the Link HTTP header, which will work with any content-type, not just text/html.

POnakS commented 2 years ago

Sorry, I think I've misunderstood this issue. I think having link pointing to documentation of current method is good idea, my comment does not really applies to this discussion.

(I was thinking of service discovery, i.e. getting Open API json just from domain).

dret commented 2 years ago

Why be specific about the Link header and not just recommend the pattern by recommending a link relation to use?

jkobus commented 10 months ago

If anyone comes around wandering about this, I did it like that: <link rel="service-desc" type="application/vnd.oai.openapi+json;version=3.0" href="https://example.com/.well-known/openapi">

For json it would be application/vnd.oai.openapi+json as mentioned here: https://github.com/OAI/OpenAPI-Specification/issues/110#issuecomment-364498200