aged building on city street with cyclists

A visual history of web API architecture

Saya sebetulnya ngga terlalu mengerti semua apa yang saya copy paste berikut ini, namun saya perlu untuk mengerti, karena ini berhubungan dengan iGracias. Dan dari pada saya sulit gugling dulu, lebih baik saya bookmark disini biar gampang dibacanya.

Sumber asli silahkan dibaca di

To be fair they are both beautiful buildings! Photo by Jene Yeo on Unsplash and Shinya Suzuki.

So, what’s the architecture of your web application? It sounds like a deceptively simple question — maybe even a softball first-round interview question.

Turns out, after nearly 30 years of the Internet, the answer is far from straightforward, as page one of a Google search for the above term reveals:

We should start by clarifying what we mean by the word “architecture.” At its most basic, this is a question whose answer is just a picture and some arrows.

At its most basic, software architecture is just simple shapes with arrows — just a map and a path

The Clean Architecture looks like this:

Android app architecture, as proposed by Google, looks like this:

What about web application architectures? Surely something as straightforward as a web application — one of the foundational pieces of software we were building back in the mid 1990s — will be a well-documented victory lap of classes, hierarchies and data flows by the 2020s?

Ruby web app architecture

The godfather of modern, opinionated web application architecture is probably Ruby on Rails — so what happens when we go searching? (Maybe skip the results from April 2021 😬). Not a lot of helpful results:

The Internet generally understands Rails architectures to be based on MVC, though a diagram like this doesn’t offer much in the way of guidance in how to construct even a moderately complex app. The Rails Guides site isn’t a guide so much as an index of every class in the Rails universe, with little in the way of explanation about how they fit together. Here is a more recent take as of 2017:

Even then, this seems to suggest that our app requires 3 (maybe 4?) classes, dominated by Action controllers and Active Records (aka models).

JavaScript web app architecture

By now, hopefully you have gotten the memo about the JavaScript event loop. No? Don’t worry, because every nodejs architectural diagram is just this:

What is the architecture of your nodejs web API? Event loop.

We got it node. You’re proud of your event loop.

The remaining web results when googling nodejs web application architecture are a hodgepodge of SEOd links for new developers learning to program, with a few shady certification programs thrown in the mix. I’d normally suggest you see for yourself, but I suspect these results have a higher-than-normal likelihood of giving you spyware.

Java web app architecture

The Java world has a bit more maturity when it comes to describing application architecture, though Java was widely ridiculed in the late 2000s and early 2010s for its perceived complexity and the overwrought nature of its main development IDEEclipse.

Or any IDE, really

This ancient blog about Spring Boot shows at least 4 layers with perhaps 6–7 different class types:

More recent blog posts have tried to rationalize this layered approach with the Rails MVC architectural approach:

O’Reilly predictably gives us a more disciplined discussion of Java EE architecture:

But it still feels like we are a step away from answering the meat-and-potatoes problems of software developers tasked with building web apps and APIs.

What are the classes I should expect to write when building a web application or API, and how do they fit together?

Big Company Web Application Architecture

Can we look to the giants for guidance? Microsoft has plenty to say about common web application architectures. So much so, in fact, they helpfully included 14 diagrams to aid your understanding.

To be fair, Microsoft does have a number of smart points to make, including use of Clean architecture, dependency inversion, and the importance of testability. However, those points are buried so deep under jargon about ASP.NET and Azure deployment models that it largely passes unnoticed amongst the non-MSFT developer world.

Also, they need more animated GIFs…

Too. Many. Words.

Uber recently documented its API approach, with the following stack:

This approach comes closest, I believe, to offering practical advice, but it’s predicated on big-company patterns like microservices.

Car = Microservice

As an example, Client performs a request to a back-end service…Users can configure the internal functionalities of a client, like a request and response transformation, validation of schema, circuit breaking and retries, timeout and deadline management, and error handling”.

So…how do you write the “back-end service?” And doesn’t the service have the same considerations (validation, parameter extraction, etc) of this top-level API gateway? According to Conway’s law, your API structure is your team structure.

Most companies aren’t going to have dedicated teams for each aspect of their API, so the “Client” layer described by Uber probably won’t exist at your company — it will be a “Service” layer that does the thing the API is supposed to do, and we need to know, now, how to design that Service.

Why is this so hard?

The truth is — most web applications are small, and their architectures don’t matter. They’re going to be rewritten every N years, so they emerge as a monolith maintained by one or a handful of developers…and it’s fine.

I’ll just rewrite it once Coinbase releases its JavaScript framework in 2025

Larger applications by FANG have teams devoted to every piece of the stack, plus tooling, security, source code management, etc. But what about developers and projects who want to build testable, maintainable, scalable, large production apps? What are the classes, data flows, and hierarchies that we should expect to build?

Toward a Clean API Architecture

At Perry Street Software, we have been building a large API for the past decade to power our family of dating apps. We recently have devoted time to codifying and upgrading our server API architecture in a way that actually maps quite closely to the Clean architecture, with inspiration from functional/reactive programming paradigms that have (rightly) become popular of late.

We call this our Clean API Architecture. Before we begin, however, we are going to need to take a brief detour into the execution flow of typical web applications. Remember, any architecture is just a picture and some arrows, a map and a path.

The island is code; the red line is an execution path; the map is an Architecture.

Too often the line and/or the arrows are skipped right over — we should pause to explore the nature of the arrows themselves.

Leave a Reply

Your email address will not be published. Required fields are marked *