Proper REST with JSON?

Is a proper REST implementation with JSON really possible? That’s been my question since I started the implementation of a self-proclaimed REST API. Can anybody help?

In the first place, we decided to go with JSON for the data format because the client is able to consume it very easily. The transport is standard http. One of the main drivers for the implementation is performance. It needs to be freaking fast because an AJAX interface is depending on it. This is why only very simple objects are streamed to the client, but when more data is required… well… then what? We really have to figure out a way to link to this data and enable the client to retrieve more detail when it’s required.

We need to implement some way of referencing other resources. According to Roy Fielding a proper REST service is all about discovering and referencing. But… implementing your own way of referencing and dereferencing is against the rules of the hypertext constraint apparently.

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].

There must be a standard of some sort for JSON that allows us to comply with those rules. What we found so far is Hyper schema and it seems to be a decent piece of work by Kris Zyp (it’s part of Json Schema). What we extracted from it, is the use of a ‘href’ attribute to reference other resources.

{
  "project": {
    "name": "LANG"
    "baseLanguage": { "href": "languages/en_US" }
    "versions": [ { "href": "versions/1.0" }, { "href": "versions/1.1" }, { "href": "versions/2.0" } ]
  }
}

Your thoughts would be most welcomed!

  • Facebook
  • LinkedIn

5 thoughts on “Proper REST with JSON?

  1. Apart from the alternatives mentioned I think your current solution – using “href” for linking – is fine. It’s simple which is a big plus. Nonetheless it’s a compromise, strictly speaking it isn’t 100% HATEOAS since the client does need prior knowledge of the JSON schema convention in order to traverse links.

    • We added ‘id’ in the meanwhile. Although the client does not strictly follow a standard to discover and follow links, ‘our’ client now knows how to follow links consistently over the entire REST api, nonetheless where it is, or what resource it is retrieving.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>