• 1-800-224-1462 US & Canada toll free
Webhooks on their way to release!Read More

The Whats and Hows of Hypermedia APIs (Part 2): Hypermedia Types

Read on 3 minutes

One of our recent articles was dedicated to Hypermedia APIs and pluses of their use. Today, we are going to dwell on a related topic, that is, types of hypermedia you can choose for your API.

First of all, let us briefly summarize why hypermedia APIs are worked with. Very often, the reason lies in standardized responses and linking.

A great deal of enterprises defines their custom API format that is usually a JSON response perfect for their data model. For example, very often one company’s API client cannot communicate with the one of some other enterprise and vice versa. This results in duplication of API clients doing almost the same.

Just as it is stated on W3C, JSON has no built-in support for hyperlinks, which are a fundamental building block on the Web. This means that API endpoints are linked together by documentation, and you will need to grope for what you want to find.

Hypermedia approach makes away with these pains by establishing link connections between API endpoints and documentation as well as potential actions and related endpoints. This makes it clear what the next actions a client may want to take are. Moreover, a hypermedia type client developed for one API can understand the format of another API and communicate with minimal duplicated effort.

Now, that we are aware of why hypermedia is a good thing, let us proceed with media types that are used as the message model for all request and response payloads regardless of the object or collection being passed. There are two major options: to use an existing type and  create your own.

You can build your own hypermedia type by either making a custom type or using the profile link relation. Consult Building Hypermedia APIs in HTML5 and Node if you would like to go for the first variant, or read The 'profile' Link Relation Type to add hypermedia flavor to a type.

Let us move to some ready formats. A lot of hypermedia types have been proposed (CCXML, RDF/XML, SensorML, Sitemap XML, SMIL, SVG, TriG, TriX, Turtle, and others) but not all of them are practically implemented. Some of the commonly used types are HAL, JSON-LD, and Collection+JSON. We are going to talk about each of them below.

HAL (Hypertext Application Language) is one of the prominent media types in present-day APIs thanks to its being easy to use and understand. It is a little bit similar to HTML, as it drives various types of applications via hyperlinks. The difference here is that HTML is designed to help ‘human actors’ move through a web API to achieve their goals whereas HAL does that for ‘automated agents’.

This hypermedia format will make your API not just easy to work with, but also easy to serve and consume using open-source libraries available for most programming languages. Adopting HAL is also attractive for client developers, as its documentation is comfortably discoverable from within the API itself. For more information on this hypermedia type, go to this Internet-Draft.

Here is a simple example taken from the draft:

{
     "_links": {
       "self": { "href": "/orders/523" },
       "warehouse": { "href": "/warehouse/56" },
       "invoice": { "href": "/invoices/873" }
     },
     "currency": "USD",
     "status": "shipped",
     "total": 10.20
   }

JSON-LD is a Linked Data format based on JSON that is easy for us to read and write. It is perfect for REST Web services, programming environments, and databases. The thing you will like about JSON-LD is that it can be adopted without causing any breaking changes to APIs. Its syntax does not bother deployed systems and provides a smooth migration path from JSON to JSON with added semantics. Here you can find information about its grammar, data model, basic and advanced concepts, relationship to RDF (Resource Description Framework) and other linked data formats, etc.

See the example taken from the official JSON-LD website:

{
  "@context": "http://json-ld.org/contexts/person.jsonld",
  "@id": "http://dbpedia.org/resource/John_Lennon",
  "name": "John Lennon",
  "born": "1940-10-09",
  "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}

The Collection+JSON is a JSON-based media type designed by Mike Amundsen to manage and query simple lists such as contacts, tasks, blog entries, etc. It supports a limited semantics defined by the CRUD (Create, Read, Update, and Delete) pattern as well as predefined queries including query templates. To find more details, visit Mike Amundsen’s website where the following example is taken from:

{ "template" : {
    "data" : [
      {"name" : "full-name", "value" : "W. Chandry"},
      {"name" : "email", "value" : "wchandry@example.org"},
      {"name" : "blog", "value" : "http://example.org/blogs/wchandry"},
      {"name" : "avatar", "value" : "http://example.org/images/wchandry"}
    ]
  }
}

You may also find this Collection+JSON Discussion Group interesting.

Some final points. Each hypermedia type is good for different things. For example, HAL is a perfect choice if you want to keep it simple, JSON-LD is great for existing API responses augmentation, and Collection+JSON will definitely make you happy if you are looking for a full-featured solution.

P.S. If you would like to know how APIs can help your business expand, contact us by clicking the button below.

The following two tabs change content below.

Lexy Mayko

Marketing Manager at API2Cart
Marketing manager, API fan, nerd, perfectionist, British humour enthusiast, literature and history geek.

Related Posts:

comments powered by Disqus

Chat now
Hi! I'm Vitaliy. Hit me up with any questions.
×
Need Help?

Request a FREE Trial

×

Schedule a Call

Need help or advice? Let's discuss how API2Cart can help your business.

Let our expert tell you more!

Your browser is out-of-date!

Update your browser to view this website correctly.Update my browser now

×