The json home Format

Json-home is a format to describe home documents for RESTful web application, proposed by Mark Nottingham. The current status of the specification is still draft. Please note, that a draft specification is work in progress.

The following description of json-home is taken from the draft specification (http://tools.ietf.org/html/draft-nottingham-json-home-02) itself:

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 that 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 were documented by a document format like WADL [2] 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 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].