Over a million developers have joined DZone.

API Best Practices: Hypermedia (Part 2)

· Integration Zone

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

[This article was written by Mike Stowe.]

Part four of the API design best practices series. Read part one: Plan Your API.

Or jump to part one of the hypermedia sub-series.

The Harsh Reality of the State of Hypermedia Specs

Hypermedia sounds great in theory, but theory only goes so far. Where really shines, or completely fails, is in implementation. Unfortunately, as is still a relatively new aspect of web based APIs, there isn’t one specified way of doing things. In fact, you’ll find that even some of the most popular APIs operate completely differently from each other.

After all, there are several different hypermedia formats available for API providers to choose from. Just for starters there is HAL, Collection+JSON, JSON-LD, JSON API, and Siren! But the list doesn’t stop there, as some popular APIs have even elected to create their own format.

For example, while PayPal’s API closely mimics the JSON API format, it goes a step further and adds a method property (not part of the JSON API spec), creating a more flexible spec and transforming it from being resource driven to being action driven:

"links" : [
   "href" : "https://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA",
   "rel" : "self",
   "method" : "GET"
  }, {
   "href" : "https://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA/execute",
   "rel" : "update",
   "method" : "POST"

This has the potential to let developers create a more agile client based on the actions (and methods) available to them. However, for developers not familiar with PayPal’s format, but familiar with JSON API this may cause slight confusion (although it should be quickly remedied by reading their docs).

VerticalResponse, on the other hand, has taken a different, albeit interesting approach. For their API they likewise start with the basic JSON API format, but for some reason decided against the universally accepted “href” or Hypertext Reference property, instead opting to use “url” or the uniform resource locator as the link URI identifier:

"links": {
    "up": {
        "url": "https://vrapi.verticalresponse.com/api/v1/contacts"
    "lists": {
        "url": "https://vrapi.verticalresponse.com/api/v1/contacts/1099513934863/lists"
    "messages": {
        "url": "https://vrapi.verticalresponse.com/api/v1/contacts/1099513934863/messages"
    "stats": {
        "url": "https://vrapi.verticalresponse.com/api/v1/contacts/1099513934863/stats"

Personally, I would recommend staying with the uniform “href” attribute as it denotes a reference to a hypertext link and is not as exclusive as an URL- which is not (although it commonly is) to be confused with URI. But you can read more on that here.

On the other hand, Amazon’s AppStream API, Clarify, Microsoft’s Lync, and FoxyCart all prefer to follow HAL or the Hypertext Application Language format. HAL provides a simple format for nest-able links, but like other specs omits the methods property as included by PayPal, making theirs truly unique in that sense:

  "_links": {
    "self": {
      "href": "https://api.foxycart.com/taxes/31588",
      "title": "This Tax"
    "https://api.foxycart.com/rels/store": {
      "href": "https://api.foxycart.com/stores/66",
      "title": "This Store"
    "https://api.foxycart.com/rels/tax_item_categories": {
      "href": "https://api.foxycart.com/taxes/31588/tax_item_categories",
      "title": "Tax Item Category relationships"

However FoxyCart takes it one step further, not only taking advantage of hypermedia, but offering multiple formats for their clients to choose from, including HAL+JSON, HAL+XML, and Siren.

This, however, highlights once again one of the biggest challenges with hypermedia driven APIs, the abundance of ideas and specs available for execution. While on one-hand I believe that by supporting both XML and JSON, as well as having multiple JSON formats FoxyCart is by far the most flexible (format wise) of the APIs, not having a singular standard for each language does present the challenge of forcing developers (and hypermedia clients) to support multiple formats (as they integrate more and more hypermedia APIs), while also having the understanding that not one format meets every API’s needs.

The good news, is that despite these growing pains, we are starting to see companies adopting certain specs over others, while also identifying areas for improvement (such as with PayPal’s adding of methods to JSON API). Next week we’ll take a look at some of the most popular formats out there in-depth, keying in on the strengths and weaknesses of each.

But it’s important that as you build your API, you understand WHY you are building it the way you are. And this extends into how you build your hypermedia links, and whether or not you choose to take advantage of a standardized format (recommended), or venture off on your own to meet your developers’ needs. One of the best ways to do this is to explore what others have done with their APIs, and learn from their successes, and their mistakes.

It’s also important to consider where technology is going. And as more and more formats become available and change in popularity, it may be smart to follow FoxyCart’s lead – taking advantage of the spec that best meets your developers’ needs, but also keeping the link format decoupled enough from your data that you are able to return multiple formats based on the content-type received. Something that will allow you to take advantage of this best practice, while also being prepared for whatever the future may hold.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.


Published at DZone with permission of Ross Mason, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}