RFC 5785 conventions & suggested OpenAPI document locations

[shockey]

RFC 5785 "Defining Well-Known URIs" provides for a standardized path where documents for...

"the discovery of policy or other information about a host ('site-wide metadata') before making a request"`

...can be placed, for easy discovery.

Should the OpenAPI Specification be modified to suggest using a /.well-known/ URI for APIs that occupy the root level of a hostname?

[darrelmiller]

It also says

well-known URIs are not intended
for general information retrieval or establishment of large URI
namespaces on the Web. Rather, they are designed to facilitate
discovery of information on a site when it isn't practical to use
other mechanisms;

I think it makes more sense to provide the OpenAPI description at the root of an API or use something like apis.json to enable discovery. I don't believe that discovery of OpenAPI descriptions meets bar for creating a well-known URL.

[adjenks]

@darrelmiller Really? You don't think so?
Take a look at "host-meta", a defined "well-known" uri: https://tools.ietf.org/html/rfc6415
It's used to do similar things that OpenAPI does. The description is

This specification describes a method for locating host metadata as
well as information about individual resources controlled by the
host.

So, just like OpenAPI describes how resources work for a host, so does "host-meta", and "host-meta" is already registered as a well-known uri. I feel like this is precisely what it's for, providing commonly used information about the host.

I actually found this issue because I was going to open it myself if it didn't exist.

[adjenks]

@shockey Do you have a proposed uri?
/.well-known/openapi.yaml ?
Or should could/should it have a sub-namespace? I'm going to host mine at the url I just mentioned, even if it's not a standard yet, I think it should go there.

[jgustie]

I just came across this issue and while looking into it also stumbled on a draft informational RFC that proposes a web link with the service-desc relation. In theory the actual location wouldn't matter (the document could be hosted on a separate host for instance): so long as the service returned a header along the lines of Link: </openapi.yaml>;rel="service-desc";type="application/vnd.oai.openapi".

[ioggstream]

This I-D proposes to register service-desc to Well-Known URI IANA Registry https://ioggstream.github.io/draft-polli-service-description-well-known-uri/draft-polli-service-description-well-known-uri.html

Feedback welcome. @shockey In case it fits we could delegate the issue to this I-D.

[DavidBiesack]

The issue with using the service-desc link is: which operation/endpoint returns this link? If returned with normal operation responses defined by the OAS document, there is no guarantee that every API will have a safe and discoverable operation that one can use; it also requires that the operation have have a security requirement that an arbitrary client can satisfy.
One can include the service-desc link in a heath check endpoint as per https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check, but that does not really resolve this because a) there is no .well-known path for the health check, and b) we should not require providers implement a heath check operation in order to enable discovery of the OpenAPI definition / service description).
I personally prefer using a registered .well-known path for this, such as .well-known/openapi or .well-known/open-api (not .well-known/openapi.yaml or .well-known/openapi.json - use an Accept header to request a specific format, perhaps default to JSON)
We should also address what security requirement such a path should have (i.e. security: {})