Follow application rules, not a directory index
03The shared prefix locates application-defined resources. It does not supply a common metadata format, a hostname discovery algorithm or an index.
In a separate example, /.well-known/ returns 404. There is no common directory resource, listing format or mandatory status code defined by this RFC.
Source for this drawing: RFC 8615 · Read RFC section 3 ↗
New to this? Start hereA quick picture + helpful background
A message needs an address.
Think of a packet as a small addressed envelope. Devices pass it onward; transport protocols decide what delivery promises an application gets.
Helpful first, if these ideas are unfamiliar
These pictures are analogies to help you learn. The linked RFC explains the actual rules.
Terms in this drawing
- Media type
- A label, such as application/json, identifying the format of a representation.
- Metadata scope
- The resources or application to which discovered information is meant to apply.
- Default port
- The port supplied by a scheme when no explicit port is present.
Related RFCs and changes
“Updates” changes part of an earlier RFC. “Obsoletes” replaces it. This list shows selected related documents.
The application defines where to look, what the response means and which resources it covers.
- RFC 8615 does not define how to choose the hostname, how to discover a well-known URI for a particular application, or the scope of obtained metadata. Individual applications need to define discovery and applicability; implementations guessing these boundaries can create security problems.
- Applications typically use the scheme’s default port. If an alternative port is used, the application MUST specify it explicitly. Choosing https://api.example in this demonstration is an example application rule, not a hostname derived from an email address or arbitrary service name.
- Registrations MAY define additional path components, query strings, fragment identifiers and protocol details such as HTTP method handling. Do not invent these by appending arbitrary strings. The registered-name component remains separate from such application-defined extensions.
- The prefix resource /.well-known/ has no generic format or media type defined here, and clients should not expect it to exist. Registration does not require every origin to implement a name, guarantee success, prescribe GET or promise a directory listing.
Fictional contract: choose api.example, use HTTPS on its default port, GET /.well-known/picnic-info, parse application/json, and apply the picnic metadata only to the named application on that origin. The 200 response is a chosen successful observation. A separate example GET of bare /.well-known/ receives 404; neither 404 nor GET is mandated by RFC 8615, and a server could expose a resource there without creating a universal index format.
Read the RFC section ↗