OpenAPI-Specification

OpenAPI-Specification copied to clipboard

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?

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.

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?

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.

+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.

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.

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

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

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

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

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