When HTML Can Be Better Than JSON 🔊

Start looking at the Web as a network of computers, not a network of browsers

The picture of a sleeping lion; his head is RESTing over a stone.
Listen to the audio version!

HTML-like content types can provide better foundations to build APIs for the Web

There’s a server somewhere, even if you don’t see it.

The code example that shows how to parse an HTML file using JavaScript to look for hyperlinks. There’s a function with the name “index for links” that accepts an HTML string. The function parses the HTML and queries all the anchor tags. After that, it uses the “map” and “reduce” functions to return a data structure containing links and the number of occurrences of those links in the page.

Given how HTML defines anchor tags, you can write code to crawl any website and follow links, as long as the author of the website can produce a meaningful message that follows the HTML specification of how to create anchors.

The code example that shows a test script submitting a feedback form. The script looks up for the classes “feedback form” to submit the form and “feedback content” to input the feedback as text.
The code example that shows a test script submitting the feedback form in a page where the form is in the navigation bar. The script, represented by the function "send feedback," remains unchanged but still works, even if the browser renders the form in a completely different way. Look at the differences of the HTML from this example to the previous one.

Do not create HTML attributes that are test-specific

The code example that shows how the script for the designer's bookmark would be. It has the function “simulate bookmark highlight.” The function queries all the elements with the class “company privacy always anonymous,” iterates over them and adds a solid red border with the size of 3 pixels.

You can enhance the website’s HTML to provide attributes that any script can use, including third-party consumers.

The code example that shows a response in JSON containing the data for the latitude of Sydney. The code retrieves the latitude and outputs in an alert using a function called "get latitude from."
The same code example as before, only now the server renamed the property “locations” to “regions.” The code for the function "get latitude from" breaks and the alert doesn’t work. The error is "Cannot read property ‘Sydney’ of undefined." To see it, open the snippet in the JSFiddle website, then observe the Browser Console.
A JavaScript code example that shows a response in HTML containing the data for the latitude of Sydney. The code retrieves the latitude using the browser’s “query selector all” function and outputs in an alert.
The same code example as before, only now the server renamed the unordered list to a description list. Also, the server renamed the header from “Locations” to “Regions.” None of those changes break the code for the function "get latitude from." The alert always works, as long as the element with the class "sydney-latitude" has the correct value.
The same code example as before, only now there's a new latitude in the "description list" for the "Sydney" region. The alert outputs both latitudes separated by a comma.

If the server returns raw JSON as a response, clients have to write code that is tightly coupled to the structure. Any significant change to the structure break the clients.

A Tweet from Roy T. Fielding, the author of the REST architectural style. It says: "The reason to make a real REST API is to get evolvability. A “v1” is a middle finger to your API customers, indicating RPC/HTTP (not REST)"

HTML is an API to the browser. What HTML has is a specification that can give you for free a lot of the benefits an API built with JSON without a hypermedia specification doesn’t have.

server -> HTML ->          browser           -> human brain
server -> HTML metadata -> Some HTML parser -> machine
A tweet from Matt McClure in response to the previous tweet from Roy Fielding. It says: "And isn’t giving your customers a REST API without client development tooling to complement it also giving them the middle finger?"

I believe ideas should be open/free. This is a non-profit initiative to write about challenging stuff you won’t find anywhere else. ~7 min post every few weeks.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store