What is a Hypermedia API Anyway?

Hypermedia is one of those terms that get floated around every time a RESTful web services conversation starts up. Or maybe I am just terrible at dinner conversations…  At its core, Hypermedia refers to anything that is not text. So in HTML the hypermedia portion would be the image tags, hyperlinks, resources (css/javascript), etc… Thats great, but in APIs, you don’t see a lot of images getting pulled in. Its basically just JSON responses… So, where does Hypermedia come in to RESTful APIs?  Fielding put it this way… 

When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions… Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types. –Roy Fielding

 

So, what he is saying here that in addition to presenting back the data, or information, you should also present back some controls to act on the data. 

Here is an example.  I will use a speaker/session interaction to show what I mean. 

A typical response to a “Speaker” request from an api would look like this…

{

    SpeakerId: 4982174123,

    Name:  “Jonathan Mills”

    Bio: “This is Jon’s Bio”

    Sessions: [{

        Title: “This is my session”,

        Description: “This session is awesome”

    }]

}

Ultimately, this is fine, but it does not help a developer understand what the API is trying to do without consulting lots of documentation. Adding in some “Hypermedia” or in Fielding’s words, some controls will add some clarity to the API consumer as to what options they have in using the API. Check out the response with some hypermedia added in. 

{

    _id: 4982174123,

    Name:  “Jonathan Mills”

    Bio: “This is Jon’s Bio”

    Sessions: [{

        _id: 12379485749

        Title: “This is my session”,

        Description: “This session is awesome”

        _links:{
           Details:{
              “href”:”http://localhost:8080/Sessions/Details/12379485749″
           }
        }

    }]

    _links:{
         ExtendedBio:{
             “href”:”http://localhost:8080/Speaker/Extended/4982174123″
         }
    }

}

Adding in the Hypermedia links, gives the API consumer a clear understanding of what other options they have when dealing with your API. 

Ok, now realistically, this is just one component of a larger conversation but this should give you a pretty good understanding of what someone is talking about next time they throw out that term… 

 

Leave a Reply

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