Fork me on GitHub

Is my API RESTful when I use (only) JSON?

Short answer: no. Long answer: no, not yet. One of the key constraints on REST is that a RESTful API must use hypermedia formats (the HATEOAS constraint). Unfortunately, JSON is not a hypermedia format. There is no predefined way to deal with link discovery in JSON. One API could use the following for link discovery:

    {
    "_links" : [
        {
            "rel" : "self"
            "href" : "http://example.org/foo/bar"
        },
        {
            "rel" :
            ...
        }
    ]
}

while another API would use something like this:

    {
    "hyperlink" : [
        "self" : "http://example.org/foo/bar",
        "next" : "http://example.org/foo/bar/2",
    ]
}

Although JSON does't have inherent hypermedia support, some standardisation is on its way to change that. JSON-LD, which is already an official W3C standard, and HAL, which is a personal project, formalize the expression of links in JSON so that clients can instantly follow and discover these links without having to rely on out-of-band additional knowledge.

See also

Caveats

  • Because JSON by itself has no hypermedia support, using JSON for APIs can and most probably will result in tight coupling between clients and servers. Servers need to know exactly how you provide links in JSON (if at all). JSON-LD, a W3C Recommendation, or HAL can reduce this coupling and allow you to formally present (hypermedia) links in your API.

Topics