Home Documents for HTTP APIs

1.  Introduction

   There is an emerging preference for non-browser Web applications
   (colloquially, "HTTP APIs") to use a link-driven approach to their
   interactions to assure loose coupling, thereby enabling extensibility
   and API evolution.

   This is based upon experience with previous APIs which specified
   static URI paths (such as
   "http://api.example.com/v1.0/widgets/abc123/properties") have
   resulted in brittle, tight coupling between clients and servers.

    Sometimes, these APIs are documented by a document format like
   WADL [1] that is used as a "design-time" description; i.e., the URIs
   and other information they describe are "baked into" client
   implementations.

   In contrast, a "follow your nose" API advertises the resources
   available to clients using link relations [RFC5988] and the formats
   they support using internet media types [RFC4288].  A client can then
   decide - at "run time" - which resources to interact with based upon
   its capabilities (as described by link relations), and the server can
   safely add new resources and formats without disturbing clients that
   are not yet aware of them.

   As such, the client needs to be able to discover this information
   quickly and efficiently use it to interact with the server.  Just as
   with a human-targeted "home page" for a site, we can create a "home
   document" for a HTTP API (often, at the same URI, found through
   server-driven content negotiation) that describes it to non-browser
   clients.

   Of course, an HTTP API might use any format to do so; however, there
   are advantages to having a standard home document format.  This
   specification suggests one for consideration, using the JSON format
   [RFC4627].



https://datatracker.ietf.org/doc/draft-nottingham-json-home/?include_text=1