A visual history of web APIs

This is a very basic intro to APIs that was part of an upcoming article about API strategies.

There was a time when simply having a website would entitle a company to call itself “digital”. Almost all content on a website was for humans. Then the search engines emerged and websites started to be optimised for them to be able to reach their target audience.

Nevertheless roughly 4–10% of the information in the world is accessible through public search engines and the rest are hidden in deep web (not to be mistaken with dark web or darknet). So far a web page was a mixture of content and the UI that made it easy for humans to digest. The page (in HTML format) was usually “rendered” on the server side. Most user interactions were processed on the server side which required a full page reload — the server usually ran some business logic and put the resulting data (also called Model in many frameworks) in a “template” (usually called View) to render a new HTML page.

With the advent of Ajax and Dynamic HTML, the web page that was already loaded into the browser started to talk to the server and update itself. Despite its complexity, this way of handling UI moved the needles of conversion and user experience in the right direction. Therefore the developers pushed the idea to the point where the main part of the UI only needed to be loaded once and could update itself just by passing and receiving data to the server while handling business logic in the browser. Single page apps (SPA) were born!

This was very similar to the experience the users were getting from the installed mobile apps. The only difference was that the HTTP protocol was used to also serve the UI in the web world.

With the advent of REST, even backend services started to talk to each other in a machine friendly format (usually JSON) over the web protocol (HTTP). This is where things started to get interesting. Apps could leverage the power of various services (mostly running on the cloud by this time) using now-called Application Programming Interfaces (APIs). There is no limitations to how many servers an app can talk to.

In many ways APIs are the younger brother of the RPC on steroids. The real power of APIs is their simplicity for the machines and programs to talk to each other regardless of their architecture, location or even programming language.

Sidenote: we are using “server” and “service” here interchangeably for the sake of simplicity. The company offering is the “service” while the actual code running on a machine to expose that service is the “server”. In practice the part of the code that is run on the browser is called “frontend” while the rest is called “backend”. The backend can run on a server in the cloud or on premise. Even then, it can run on a dedicated machine (virtual, containerized or physical) or it can run on a one-off basis (serverless). But these technical details are not super important for an intro to the API strategy.

Today billions of people use APIs on a daily basis to get through their life. Anything from a simple search to banking transactions (eg. SWIFT) to playing music (eg. Spotify) and from controlling IoT devices (eg. Philips Hue) to even controlling the very essence of the cloud (eg. AWS) uses APIs. There are even services that connect these APIs together to create more tangible applications (eg. IFFT). APIs themselves are mostly offered as SaaS but even PaaS offerings like Azure have an API.

Public vs Private vs Internal APIs

Just like services behind them APIs have a vast diversity:

• public APIs: these are usually the ones that come to mind when speaking of APIs. The Twitter, Facebook and YouTube APIs are some of the famous ones. Trivia: Facebook’s recent Cambridge Analytica scandal is a good example of power of APIs abused. The public APIs are usually the main area of building an API strategy. Nevertheless, there are other groups of APIs that are equally important.
• private APIs: are usually shared between a company and its partners or customers. For example Spotify might have exposed an API to Volvo cars that have built in support for its services. These APIs can make or break strategic partnership between companies and if done correctly can generate a great source of revenue.
• internal APIs: are used by your own front-end (web, mobile) to talk to your backend. With the advent of microservices it is increasingly common for backends to talk to each other using a internal APIs which is also called server-to-server (S2S) or inter-server. The internal APIs usually don’t have an extensive documentation and since the code is available internally, usually that serves the purpose. Nevertheless they are an important facilitator for separation of concerns and are a great tool to tame the complexity of the server implementation. An example is Tesla Model S API that’s used by its own mobile apps to control the vehicle.

Protected vs Open APIs

Depending on the access level, APIs fall in two categories:

• protected APIs: the ones that need some sort of authorization to work (usually using OAuth 2)
• open APIs: the ones that are open to the web, just like regular web pages and anyone can make calls to them. The open APIs usually have some sort of rate limiting to prevent DDoS attacks and keeping the infrastructure costs under control.

SDKs

To facilitate working with the API many top services come with a software development kit (SDK) that is usually a thin wrapper on top of the language-neutral API endpoints (also called API surface) providing a language-specific library for doing the ceremonies of talking to the API. Using an SDK facilitates API calls to asynchronous function/method calls native to a particular language.

Developer portals

Unlike user interfaces or web pages, APIs can’t claim to be “intuitive”. In fact most APIs are merely endpoints that return results and status codes. Threfore many APIs come with an accompanying developer portal which is a content site that provides documentation (tutorial, examples, endpoint references), links to SDKs, token generation, licensing, pricing, etc.

There has been some efforts to make the APIs discoverable (eg. HATEOAS or JSON API) but to a large degree APIs are as diverse as the machines running them and the developers building them.

The developer portals more or less serve as “the UI of the API” without being an actual use case for the API.

This article was originally part of a deeper article about API strategy. Make sure to follow me if you’re interested to API, programming and product management.

Did you like what you read? Follow me here or on LinkedIn. I write about technical leadership and web architecture. If you want to translate or republish this article, here’s a quick guide.