[liveoneggs]

a principal of REST which is often ignored or improperly implemented is hypermedia-driven discovery. You should be able to discover the entire api via a top-level entry point which will return a bunch of links.

https://en.wikipedia.org/wiki/HATEOAS

[nailer]

It's really weird:

- SOAP had discovery

- XML based REST APIs had discovery (via HATEOAS)

- JSON based REST APIs inevitably never have discovery (looks like there's no standard JSON version of the 'link rel' from HATEOAS)

- GraphQL has discovery

[liveoneggs]

if you implement swagger (now openapi) then you put the discovery in: https://github.com/OAI/OpenAPI-Specification/blob/master/ver...