Clone wiki

hm-json Browser / Home

Welcome to hm-json Browser

Last updated 2014-Mar-20

hm-json Browser is a JavaScript client that can browse and interact with hm-json (Hypermedia JSON) APIs. It is intended to: 1. Show that JSON can be hypermedia, and 2. Make discovering and using an API as easy as surfing the Web.

Keep reading for a complete description of the simple hm-json standard.

Live Demo

Screencap of the live hm-json browser demo

Visit http://hm-json.ratfactor.com/ for a live demo of the browser being used to serve up a simple API. See how easy it is to explore and use a RESTful API. For more information about the PHP demo, see hm-json ResourcePhp.

What it Does

A Web browser displays a user interface of text and links based on HTML data. The hm-json Browser displays a user interface based on JSON data (with hypermedia).

The hm-json Browser can make complete use of hm-json compatible resources. It natively supports HTTP methods GET, OPTIONS, PUT, POST, and DELETE. Because of this, application developers can discover and use APIs without the need for test applications or even documentation.

What is hm-json?

hm-json stands for Hypermedia JSON. By using hypermedia 'links' to connect one URI (or URL if you prefer) to another, hm-json allows JSON data to offer a uniform interface and describe an application state (a concept known as Hypermedia as the Engine of Application State or HATEOAS). According to REST creator Roy Fielding, these are essential components of REST APIs.

In a nutshell, hm-json is JSON data containing a hypermedia property which has a title and description of the resource as well as links describing the methods supported by the resource (which are the resource's interface) and other related resources in the API.

The hm-json Conventions

Here is the smallest valid hm-json resource:

{ 
  "hypermedia": { }
}

As you can see, the only requirement is that the JSON data contain a hypermedia property. While valid, this hypermedia is very unhelpful.

Here's a more typical example (taken from the demo - see Live Demo above):

{
    "hypermedia": {
        "success": true,
        "title": "The Book Collection",
        "description": "The entire collection of books. You can get the list of books and POST a new book here.",
        "links": [
            {
                "title": "/",
                "method": "OPTIONS",
                "href": "/",
                "rel": "parent",
                "description": ""
            },
            {
                "title": "Book List",
                "method": "GET",
                "href": "/books",
                "rel": "self",
                "description": "The full list of books in this collection."
            },
            {
                "title": "New book",
                "method": "POST",
                "href": "/books",
                "rel": "self",
                "description": "POST a new book to the collection."
            },
            {
                "title": "Self",
                "method": "OPTIONS",
                "href": "/books",
                "rel": "self",
                "description": "An available HTTP method for this resource."
            },
            {
                "title": "{book_id}",
                "method": "OPTIONS",
                "href": "/books/{book_id}",
                "rel": "child",
                "description": ""
            }
        ]
    }
}

The above example was last updated on 2014-Mar-20 and now contains the success property in the hypermedia.

The hypermedia element can contain four properties:

  • success - indicates whether the client should consider the outcome of the request as being successful or not
  • title - terse description of the resource itself or the outcome of a method action
  • description - more detailed description
  • links - a list of other resources and methods which are related to this resource

Success may be defined in any way that you like and the title and description are likewise open to be used however you see fit. The live demo shows some examples of appropriate uses for these properties.

The links defined in the links list should each contain the following properties:

  • title - the text name of the link (may describe an action)
  • method - the HTTP method to be used (such as GET, OPTIONS, PUT, POST, or DELETE)
  • href - the URI (may be templated, see below) of the resource
  • rel - the relationship of the link to the current resource
  • description - a brief description describing what the link represents or what action will occur if the link is used

URI Templates

The hm-json Browser supports link hrefs which contain RFC 6570 Level 1 URI Templates. Level 1 templates are nothing more than variable expansion (which hm-json calls 'parameters').

This example URI contains one template parameter, book_id:

/books/{book_id}

When a link has an href property containing one or more template parameters, the hm-json browser will present a form containing text entry fields for each parameter. You can fill out these parameter fields to complete the URL.

In this way, a single link can encapsulate any number of individual resources that have a uniform URI scheme such as

/books/12

and

/books/5000

PUTing and POSTing Data

While it is not a requirement of hm-json by any means, the hm-json Browser expects all data transferred to the server in a PUT or POST request to be JSON encoded. When you click on a PUT or POST link in the browser, it presents a text area for this JSON data. Likewise, the data is sent with a request header containing:

Content-Type	application/json; charset=UTF-8

Note: the live demo does not record any changes. Likewise, it does not reject improperly formatted JSON data.

The JSON Payload

The data your resource provides is the real JSON payload. Any properties in your JSON response at the root level that are not named hypermedia are part of the normal JSON data payload.

For this reason, hm-json is completely compatible with any other JSON format that does not use a hypermedia property at the root level. For example, here is a JSON response containing both hm-json hypermedia and a microformat:

{
    "microformats": {
        "vcard": [{
            "fn": "John Doe",
            "n": {
                "given-name": "John",
                "family-name": "Doe"
            },
            "url": ["http:\/\/www.johndoe.com\/"]
        }]
    },
    "parser-information": {
        "name": "UfXtract",
        "version": "0.1",
        "page-http-status": "200",
        "page-title": "hcard1";
        "page-url": "http:\/\/ufxtract.com\/testsuite\/hcard\/1.0\/hcard1.htm";
        "time": "T000000.0098"
    },
    "hypermedia": {
        "title": "John Doe's vCard"
    }
}

As you can see, the hypermedia property needs only to be at the root of the JSON data. Order is not important.

Updated