APIs are not Web Pages

Even though web pages might be built from APIs, they are not the same.

There’s a tendency, particularly for networkers, to classify applications by the protocols they use. If it uses HTTP, it must be a web app. The thing is that HTTP has become what it was intended to be: a transport protocol. It is not an application protocol, in the sense that it defines application messages and states. It merely transports data in a very specific way.

That’s particularly important in the age of the API and, increasingly, the age of things that might be using APIs. You see, APIs are primarily data centric constructs while web pages (think any HTML-based app) are document centric constructs. 

Data centric constructs tend to exchange, well, data. And document centric constructs… yes, exchange documents. Both might use HTTP as a mechanism to do that, but the actual payload carried differs dramatically. That’s because data centric constructs are concerned with exchanging data that is not necessarily meant for human consumption. It’s meant to provide the application with information that it can then process and display or act on accordingly. Document centric constructs, on the other hand, are meant to be consumed by human beings. Because of that they tend to include all the stuffs required to format, display, and present information.

Now, some web apps are a combination of both. There’s a framework composed of HTML that lays out the user interface, and then scripting that exchanges and processes data via APIs. The initial “load” grabs the document, subsequent interactions exchange data.

The reason I’m being so pedantic about this difference (ignoring that pedantry is my superpower) is because this distinction is critical when architecting for scale. The load generated by these interactions is different. Loading a single page is no trivial task these days. HTTP Archive, which tracks these fascinating kinds of numbers, notes that the average page required 35 TCP connections to load.

35 TCP connections.

That may be because the average document size was 24kB, comprising 889 elements.

So not only do we need to open a lot of connections, we’re taking a lot of time transferring data over those connections.

Now it is true that APIs also get objects. The thing is that except for images, almost all data is a far more compact form and it is data, not visual elements of a document or UI. For APIs, JSON is universally favored right now, and it adheres to a fairly consistent key:value paradigm, with appropriate embedded lists (arrays) of objects within it. Pagination and a smaller screen size dictate generally smaller pieces of data at a time, displayed in preparation for user interaction. The interface already exists, the data is simply used to populate that interface. This is not the same as HTML, where both interface and data presentation often need to occur as the result of transferring the objects.

Dependencies, too, are different. Many of the optimization techniques used by ADCs and front-end optimization services focus on the web of interdependencies that exist naturally in an HTML document. You can’t layout the page until you’ve loaded the style sheet that dictates it (CSS), and scripts may need to execute before data is processed for display (or as part of that process), and so on. The display of one object might depend on the existence of another that is not yet loaded. Hence the focus on optimizing the transfer of objects in an order that allows the UI to begin parsing and presenting information as soon as possible, giving the illusion, at least, of greater speed whether or not reality matches the illusion.  

In other words, the API returns a single, large chunk of data. It may or may not trigger additional calls to retrieve additional objects. A web page, by design, automatically will.

So… to sum up this comparison, APIs exchanging JSON are not the same as HTML even though both are using HTTP as the transport layer.

What does that mean?

It means, kids, that optimizing an API is not the same as optimizing a web page. It means that techniques like minification (stripping out white space and comments) isn’t necessarily going to improve performance of APIs, nor will reordering objects or inlining scripts and style sheet elements. It means that optimization an API depends a whole lot on design (which networkers can’t do that much about) and on the intermediaries you use to scale and secure that API.

A significant number of APIs are geared toward mobile devices. Mobile devices are infamously plagued by poor performance largely due to excessive round trip times (RTT) from DNS and the overhead of connection establishment. APIs delivered via HTTP can stand to be connected with longer TCP idle times to prevent requiring re-establishment of the underlying TCP session during the application experience. To offset the impact on capacity that has (servers can only serve so many concurrent connections, after all), using an intermediary (a full proxy) that effectively splits the interaction between “client” side and “server” side can reduce the impact of longer-lived sessions while simultaneously improving performance by eliminating the extra round trips required to establish a TCP session by employing TCP multiplexing techniques (similar to HTTP/2).

Compression, too, if your API is returning significantly large chunks of data, can be a bonus. Many API optimizing blogs and articles point out that for some reason, compression is rarely “on” at the server. There are reasons for this, good reasons, but that doesn’t mean compression shouldn’t be used at all. When appropriate, let the intermediary (proxy) apply compression, as it is usually far enough upstream to avoid the potential negative impact of doing so.

The big deal here is that optimizing an API for performance is not necessarily the same as optimizing a web application, even though both use HTTP. So if you’re really looking for a performance boost for APIs and you can’t get developers to change what they’re doing, look to the network and, as is increasingly the case today, to the architecture.