The relationship of the web APIs and the World Wide Web (the medium) has been complicated, to say the least. It feels like APIs constantly try to defy how web is supposed to work. Every time APIs do it, however fundamental laws of distributed computing inavitably punish the rebelious APIs and put them into the proverbial corner, forcing to “apologize” and retract.

We have heard the story… (If you don’t care to remember it, feel free to jump to TL;DR Punchline)

First came the attempts to implement RPC over HTTP (SOAP, XML-RPC…). Eventually we discovered the limitations of tight-coupling clients to proprietary procedure semantics and decided that we’d rather build resource-oriented APIs with actions limited to core HTTP verbs. What most people call “RESTful APIs” were born.

“RESTful APIs” in many cases worked better, simpler than RPC alternatives. For a while that made us happy. Then people who actually read Chapter 5 of Roy’s dissertation showed up and vocally pointed out that the “common REST” wasn’t actually very RESTful at all, since some of the most prominent “RESTful” APIs completely ignored such fundamental principles as, say: Hypermedia As The Engine Of Application State (HATEOAS). We were set on the course of correcting our erroneous ways and the Hypermedia APIs movement was born…

Hypermedia APIs can be very powerful. Their current definition, however, is just a step in our continous journey of building better web APIs. It is not the end of the journey itself.

Tight Coupling Is Evil

On the journey of getting to an ideal API architecture, we are basically trying to scale all aspects of API infrastrucutre: make APIs capable of taking more load, ensuring they are not siloed and that they do not lead to a management nightmare

The number one enemy of any scalability effort is tight coupling. By de-coupling various aspects of the client-server interaction, we are getting to an increasingly more scalable API design. There are multiple facets to the de-coupling effort, however, and we haven’t figured all of them out, yet.  

TL;DR Punchline: “Javascript” of APIs

Web APIs targeted at machines are behind the human-centric web in their maturity. By “Human-Centric Web” I mean the part of the web using standardized browers and the ability of human brains to process HTML-rendered content.

Comparing the progression of the “web of machines” (APIs) to that of “Human-Centric Web” (websites) we can map the milestone events of the two:

• APIs before “common REST” were like the age of Gopher, in Human-Centric Web terms: the messy era before the ubiquitousness of HTTP.
• The advancement of Hypermedia APIs establishes standard media types and is equivalent to the establishment of HTML as the lingua franca for the Human-Centric Web.

We however still do not have a “Javascript” of APIs. APIs still haven’t reached that milestone moment in the history of Human-Centric Web when Netscape launched the first Javascript implementation and forever changed how we use the world wide web.

Even the most by-the-book Hypermedia APIs currently send completely static content to the client. They do achieve one level of de-coupling by communicating controls in the response message, through link relations, but the communication is still limited to the semantics of the media type that the client knows beforehand and which would have to had been hard-coded in its implementation.

Case in point: media types can be extended with custom profiles but clients have little ability to do much interesting with the extended semantics unless they understand it beforehand. Servers are currently unable to send code leveraging the additional semantics, in the response message. This limitation obviously leads to some level of tight-coupling of server logic with client code that may be critical in certain scenarios.

Proper Hypermedia Clients Should Be Scriptable.

To achieve the next level of de-coupling, servers can leverage the ability of sending API clients executable code as part of a response message. We need a “Javascript” for APIs much like we needed one for browsers back in the day.

What would anybody use scripting on the client-side in APIs for? Well, at the least, we’d use it for all the same use-cases which we use Javascript in browsers for:

• Client-side validation
• Asynchronous, lightweight sub-requests (à la “AJAX”)
• Dynamic processing of additional message semantics on top of the semantics contained in a core media type definition.

Given how non-existent such capabilities are in current APIs, the idea may sound crazy, but Roy actually had “Code-On-Demand” as one of the core constraints that compose the REST style. It’s discussed in section 5.1.7 of the original dissertation. The idea is not really THAT crazy. Better yet, with the abundance of solutions for high-quality, embeddable scripting solutions and the wealth of experience securely sandboxing scripting in web browsers, it’s totally doable!