Web API Practices: Hypermedia API Responses

I’m sharing some of the best practices that I used in a recent ASP .Net Web API and MVC project. I recently gave a presentation to my team on the Top 5 Web API Best Practices, and I continue the series by discussing Hypermedia API responses. I struck out the word ‘Best’ intentionally. There are so many best practices out there but not all of them will suit your unique circumstance, especially in regards to Hypermedia API design. These practices happened to work very well for this project, but your mileage may vary.

I first came across the term ‘Hypermedia API’ at a job interview when they asked me if I had any knowledge of Hypermedia API. I was honest and replied in the negative. I later looked it up and a more formal acronym is HATEOAS (Hypermedia as The Engine of Application State). A good introductory article is on Wikipedia’s HATEOAS page and I will be paraphrasing from it.

A Hypermedia API is a RESTful API design principle. In essence, it relies on an APIs responses to define and guide the user’s next actions. This is in contrast to using API docs such as those generated by Swagger. A Hypermedia API will return rich media responses, most likely hyperlinks, that more-or-less self-documents.

A good example from the Wiki page is the response when a caller GETs the bank balance of account 12345:

<?xml version="1.0"?>
    <account>
       <account_number>12345</account_number>
       <balance currency="usd">100.00</balance>
       <link rel="deposit" href="https://somebank.org/account/12345/deposit" />
       <link rel="withdraw" href="https://somebank.org/account/12345/withdraw" /> 
       <link rel="transfer" href="https://somebank.org/account/12345/transfer" />
       <link rel="close" href="https://somebank.org/account/12345/close" />
     </account>

Most APIs will be designed to return just the amount, e.g. 100.00. In comparison, a Hypermedia API returns a list of URLs (the hypermedia) for all the possible actions moving forwards – such as depositing more money or closing the account. There is no need to read an API doc (though they are still helpful as a reference) or formulate a working URL to transfer money as it’s right there in the response.

It should be obvious that it takes a bit of effort and pre-planning to make your APIs HATEOAS-compliant. However, it’s not an all-or-nothing approach. You can still sprinkle some Hypermedia API sugar all over your existing APIs. One place that I used this approach is with any POST or PUT calls. Instead of simply returning the ID of a newly created record, I will return a fully-formed URI to the created/updated resource, like this:

{
    "Message": "The user was created successfully",
    "MessageDetail": "/api/15"
}

Also note how I used the same detailed message response when I wrote about Consistent Response Formats.

Granted, this is nowhere near HATEOAS-compliant but it’s a great start and it’s been really helpful for the testers to write automated API tests because they do not need to keep track of IDs formulate URLs because the resource link is provided right there.

If I had to summarise Hypermedia APIs it is all about understanding how your users interact with your RESTful API and to use that knowledge to create a more pleasant experience. User experience design can still benefit APIs even though it has no graphical user interface.

Photo credit: Abstract Machine via Visualhunt / CC BY-NC-SA


529 Words

2016-11-06 18:44 +1300