HTTP Methods (5)

HTTP Headers (1)

Miscellaneous (3)

Resources (4)

Basics (5)

Mediatypes (1)

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

Short answer: no. Long answer: no, not yet. One of the key constrains 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" : ""
            "rel" :

while another API would use something like this:

    "hyperlink" : [
        "self" : "",
        "next" : "",

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.



Copyright 2012 Joshua Thijssen and others. Like to contribute? Add your recipe to our github repository.
Looking for Puppet recipies? Try the Puppet CookBook.
Fork me on GitHub