Consider other discovery mecanismes

[OriPekelman]

1. First see #12 ad-hoc well-known urls are impossible to version or evolve. If you go for this you should probably declare clear and specific semantics (with a MUST clause) for a couple of 100 and 300 class status responses so we can use those to future proof. (something in the lines of 101 Switching Protocols / 303 See Other). But then again we are going for more complicated client code
2. Do you really want to add to all web server logs a billion lines of 404 (favicon damn you!) ?
3. This is not usable for situations in which you are not on the root of the web server.

Some other elements that could be considered:

1. I think 99% of APIs already have a discovery mecanisme with a "well-known" A DNS record "api". Go with what is already implemented. As such this seems might be a better default. Maybe complement this one? asking for application/json+api on the root .. or a well known..
2. Use a "link" element in the the head section with rel=apis of a webpage. This is the simplest to implement whi allowing for future resistance.
3. Combine all three options with a priority (first you try fqdn with api. prefix, if nothing ... look at html of / find link, if nothing fallback to /.well_known/apis or apis.json)

[njyx]

1-1 makes sense for sure - any examples in a current spec? The spec allows for things not to be in the root but then they wont be authoritative. Yes if it takes off, servers will be pinged with people looking for their APIs but I think that'll be true with whatever mechanism you use.

I disagree with 2-1: that's actually rarely true for large companies + normally there are many different API endpoints + you get no meta-data that way. You need a map. Lastly the conventions "developer.XYZ.com" and "api.XYZ.com" are generally only good enough to get a human developer there -> but the point is to enable bots.

2 - yes, this is added.

No problem with #3 but it implies we need something like apis.json :)

[OriPekelman]

1. Complementing in #13 Current spec as far as I can see does not allow for apis.json to live anywhere but the root.
2. I proposed complementing the existing convention; This way basically half of the planet is already "half api-json compliant." Proposing minimal change, usually makes for maximum adoption; I wasn't clear enough... so here is an example of a protocol (really just an example here, this needs to be thought out).

In order for a client to discover APIs linked with an FQDN (for example example.com)

I. Parse FQDN

A. if the FQDN starts with www replace with api B. if the FQDN starts with [api,developers] replace keep as sucj C. if the FQDN starts with anything else add api.

Request A record for API.EXAMPLE.COM if OK proceed if nothing go for II Request TXT record for API.EXAMPLE.COM VALIDATE response (must be json, must contain JSON-API version element or something)

If no TXT record continue:

Do an HTTPS request for https://API.EXAMPLE.COM/ with content-type application/json+api VALIDATE response (must be json, must contain JSON-API version element or something) if OK proceed if invalid go for II

II. Make HTTPS request on FQDN (https://API.EXAMPLE.COM/) with content-type text/html parse resposne if found header link ... with rel-type "apis" ...

If fails Make HTTP request on FQDN (http://API.EXAMPLE.COM/)

if Fails go for III

III. fallback to http://api.example.com/apis.json

---

Well something like this is robust, future proof, and still allows people to implment the thing with just a simple text file on the root. Still "Conforming clients" will be much more robust. We can support an api that is not forcefully HTTP Centric .. etc.