How to Use Hypermedia APIs to Deliver HTML With Adaptive Web Design

Responsive Web Design Concept. VectorGustaf Kotte from Jayway software innovation consultancy describes HTML as the lowest common denominator in a world where the number of devices is steadily growing. Yet we act as if it is the opposite, with mobile clients putting on weight while application programming interfaces (APIs) are trimmed down.

In reality, APIs and HTML can be united in a smart way for a fantastic outcome. Hypermedia APIs can do just that. With a hypermedia API, you don’t just build a regular CRUD JSON API, but you include links and controls for working with resources. Hypermedia APIs can be enhanced with CSS and JavaScript to make them human-friendly as well.

If we use hypermedia HTML APIs coupled with adaptive web design, APIs can become a powerful force behind mobile development, which in turn will allow native apps and other clients to have much shorter development cycles with lighter apps for the end user.

Two Common Programming Dilemmas

Kotte explains how Hypermedia APIs may be the solution to two main dilemmas plaguing app developers today:

Problem #1: How can we scale the development of apps?

Solution: Develop API-first with HTML Hypermedia to scale more easily. Then, the client is free to have lighter code and focus more on user experience.

Problem #2: How can we make our website work on every browser? On every device? On every platform?

Solution: Hypermedia APIs can assist in applying Adaptive Web Design (AWD) in order to make design responsive, adaptable and accessible to multiple devices.

By allowing hypermedia HTML APIs to be built with adaptive web design in mind, these two separate solutions combine to make for a powerful one-two punch architecture. A larger investment in the API results in a much cheaper per unit price for the clients, and AWD leads to a better user experience for integrators, clients and even the end users who don’t have to worry about wasting precious data and limited phone or tablet memory space on bulky apps.

Gustaf Kotte from Jayway gave a talk on using Hypermedia APIs delivering HTML together with Adaptive Web Design at a Nordic APIs event in Stockholm.

Reversing The Common Mobile Development Process

Most developers these days build native apps first, and mobile websites afterwards. For products specifically built for a mobile device, Kotte believes that we should consider reversing this common process by doing the following:

  1. Start with building the mobile web site, which acts as a hypermedia-driven API.
  2. Build a native app for the main use cases. For the rest of the app, embed a browser and point it to the corresponding webpage.
  3. Follow this same process for other mobile devices.

Under the current development pattern, Android, iOS and other clients are what Kotte refers to as “fat.” These apps require much information and activity since the API only exposes data store, not workflows and business processes. App clients then see a lot of duplicated code which causes ineffective and inefficient development and a typically diminished user experience. Also, minor changes are usually applied within each individual client, which can lead to different results and a lengthy bug-fixing process. If changes were made within the API, all clients would be immediately updated.

Benefits of Using HTML Over JSON or Other Formats

According to manufacturing industry programmer and hypermedia expert Stephen Mizell, the API-first development approach is growing in popularity, serving JSON and using CRUD and HTTP verbs for working with resources. When using a hypermedia API with HTML, you build this typical CRUD JSON API, but add to it links and potential controls to enable you to work with the resources. Kotte says this can be done by using REST Level 3, which contains hypermedia controls that allow you to expose processes to clients. Mizell contends HTML is a more optimal transport media type than JSON because a browser natively understands it.

Comcast’s Jon Moore argues that HTML ensures accessibility. Moore compares HTML accessibility to sidewalk ramps, which are meant for the disabled, but also ease the struggles of cyclists, delivery men with hand trucks and travelers with wheeled luggage. HTML is the most accessible format packed with other benefits as well…

While people will always try to put HTML in its place as for presentation only, Moore also lists many ways that HTML can be used to create richer semantics that he finds immediately useful in a programmatic API. He argues we should take advantage of the benefits of HTML’s history of wide use instead of passing it over for a flashier, newer programming language. There’s no denying that HTML’s double decade age means that it is a ubiquitous and standardized format. It’s simplicity also means that more developers understand it than any other language.

Certainly, HTML has more hypermedia controls for both reading and writing scenarios than any other option. When using HTML, you can achieve a much more visual representation of the API and how it interacts within the web browser, as HTML is equipped with the ability to test on desktops and on mobile devices. It also helps that HTML can be synced with useful tooling support to notify a developer of bugs.

HTML for APIs also keeps the goal of mobile-first design in mind. Without designing the native mobile apps first, you can follow mobile-first principles of lighter code and higher processing speeds.

Why Is Adaptive Web Design Appealing?

escalators vectorAWD is based on progressive enhancement, also known as the “escalator theory:” if an escalator breaks, it just becomes stairs. Adaptive web design begins with a fundamental API that is simple enough to function on any browser. Then, enhancements are built on top of it to enhance the user experience. It then becomes logical to apply the added values of hypermedia HTML APIs under the umbrella of adaptive web design.

To access data, Mobile clients are given the choice to use HTML as they would normally do, or they can render it in a webview. Then, they choose certain use cases to render from the webview for specified native apps to increase user experience. This means that native app developers have more flexibility in what to prioritize within an app. Add to this that the web browser can be developed as naturally responsive from the start.

But what if in the future you don’t want the API, the native mobile app and the web browser permanently interlocked? Kotte argues that it’s a fair assumption that down the line you may want to separate these puzzle pieces. He says this exit strategy can be achieved simply by using separate URLs pointing to the same end point. You can also create alerts within the code to tell you which action is happening with which flow.

Together the dynamic duo of AWD and HTML APIs allow for the same code and shared templates for both web and API, but with separate URLs, all which is optimized for both perspectives.

The HTML Hypermedia API Isn’t a Solution For Everything

Sometimes you may want to have a lighter API and fatter clients. While Kotte advocates investing in APIs for stronger strategic decisions, this must be done on a case-by-case basis. In general, coupling HTML hypermedia API with adaptive web design acts as a pretty good strategy for many mobile apps to scale development cost effectively, efficiently and with fewer bugs. For slides from this discussion, you can view the following below:

Have you used HTML Hypermedia APIs as the backbone for building native apps? If not, how would reversing your app development process help or hinder your development? Affect user experience?

If this controversial topic made you want to meet fellow developers to debate, we encourage you to! This year we are bringing together API experts on a world tour to Copenhagen, Munich, London and Seattle. Follow to learn how you can interact with the API experts in May 2015.