Hypermedia API

VerticalResponse's API generally follows the REST model, based on the principles behind HTTP. We don't overlay another data model on top, we just follow the model the web is built on: Hypermedia, with resources, locations, and links to other locations, accessed by stateless client apps.

Navigating Hypermedia API

A Hypermedia API is generally not based on remote procedure calls; it is based on navigating from one resource to another. Our API has many features which make navigation through the data much easier.

  1. You're given a "URL" field for your resource, which tells you where you are.
  2. You get links to let you know about related resources.
  3. You get links to let you know where to go from there.
  4. For collections, the items also have "URL" fields to tell you where to go to get them.
  5. You can get everywhere from the top-level resource, it has links to all the major areas
  6. You always have links that can take you elsewhere, even in errors.
  7. Every resource except the top includes an "up" link, to take you up the hierarchy - even error responses. You don't have to keep a history of where you've been to keep from getting lost.

Self-Describing Resources

More generally, this framework of self describing or self “documenting” results allows an application to know what resources can be accessed after successfully performing any given operation — a key aspect of REST. Just like how a user knows what actions they can perform when navigating a website, an application can programmatically know where it can go next. This reduces coupling between the application and the server and allows server‑side changes of resource URLs to be made without breaking the application. For example, this system of links eliminates the need for a look up table of the next available resources (e.g. a WADL file) and also reduces the need to hardcode URLs. Self describing resources also result in simplicitiy and consistency across the API.

Stateless Clients

The main advantage of a navigation-based, self-describing API is that you don't have to keep as much application state in your client code. That cuts down on how much contextual information you need to keep track of and how much data you have to keep in sync.

To make it easier to write client code, results are expressed as the full state of the resource, not as a set of changes. You don't have to keep your own copy of the resource, you can get new data without having to merge it into any old version. And if you do cache data, you can just replace the old data with the new. All you really need are a link to any resource and your authorization credentials, you can navigate from there.

Why?

Reducing the state that client code needs to keep track of makes it easier to keep multiple clients in sync, and to recover from client-side crashes, network outages and such. It should be easier to recover from errors and other issues by navigating from any response to the place where you need to be. This makes it easier to make your client code more robust

Example

The response below is returned when an application attempts to read details about a particular contact.

From this state, you can find all messages sent to the given contact by subsequently navigating to the “messages” URL provided in the result, which would return a collection of emails. Alternatively you can navigate to the “lists” URL to find all lists that the contact is a part of, and even navigate to the list that the contact was initially added to.

Note:Note that the “up” link is pretty much standard in all of the API call responses and allows you to navigate to the resource’s parent.