API first architecture or the fat vs thin server debate

API first architecture is an architecture that treats the API user as the primary user of the application. This means that API is not an alternative view in the MVC paradigm, but it has the highest priority. The main differentiators are that in “API first” the architecture enforces a complete, responsive, and well-documented API. This is especially important when targeting: mobile (Apps connect to the API), resellers (their presentation layer uses the API) and highly integrated, but decoupled, multi-product environments.

MVC reuse

The MVC architecture has been popular for a long time already. In 2004, it’s popularity skyrocketed when Ruby on Rails was released. MVC allows for high reuse in the case you have a front-end / back-end application (in the CMS sense), where customers use the front-end and employees use the back-end. This does require that you choose the same software stack for both the front-end and back-end, and make those applications as similar as possible. When the MVC strategy is executed properly, many parts of the application can be reused. Some of the parts that can be reused are: DBAL/ORM, Business Logic, Presentation and AAA. Specifically AAA (Authentication, Authorization and Accounting) can be reused by allowing employees to impersonate customers, use the same login screen and share logging facilities.

Mobile views for MVC

In 2007, Apple introduced the iPhone and from that time on the importance of web application (and websites) on small screens quickly grew. MVC applications were, and still are, very suited to facilitate small screens. All that is needed is a separate or adjusted set of views that is usable on a smartphone or tablet. The strategy of creating a single set of views that is suitable for mobile and also for desktop is called “mobile first“. This is the most cost-effective and radical approach, which requires strong leadership and decision taking, because all the software needs dramatic change, as all the views need to be adjusted. The alternative is to maintain two sets of views: one for mobile and one for desktop. The alternative views are often hosted on a “m.” subdomain. This is a simple and transparent approach.

Adding API to MVC

The dreadful “HTML5 vs Native” app development debate is going on right now and I quote Danny Brown:

Any company creating mobile apps today faces an important decision, Native or HTML5? Each one has its advantages, but choosing the wrong one could be costly. – Danny Brown

Choosing Native requires you to build a complete, responsive, and well-documented API, while choosing HTML5 requires you to redesign the views. There are arguments to defend either path and it depends on the situation what choice is best. There is one approach that will always fail: building an API as views on top of MVC. Let me explain why that fails and why so many people do it anyway.

Typically the (server-side) MVC approach leads to pages with 200 ms of load time. In this approach the server does three things: database abstraction, business logic, and presentation. This is why it is also referred to as “fat server”. An API is not responsible for presentation, executes smaller business logic per request and is therefor named “thin server“. A good API is highly optimized for speed and has typical load times under 20 ms. The means that when a mobile page is constructed there can be multiple (up to 10) calls made to render the full page within 300 ms.

Still when one took the MVC approach and is now lacking an API, the easiest thing to do is to add a few views that output JSON and call it a “RESTful API”. All you need to do is write some documentation and the boss will be happy. The fact that this API is totally unusable in real life, because it does not scale and is horribly slow, will only be noticed when the API is actually used and there is no way back.


Twitter & API first

In 2010, Twitter announced their “API first” strategy. They call this a JavaScript architecture, since they created a web application in JavaScript in a similar architecture as the mobile “apps”. This allows them to have full reuse of the API they build. Where initially the API was something “extra”, next to their web application, it then became the foundation of all other development. Their API is focused on delivering optimal integration for JavaScript programmers by using a RESTful JSON API. But they are also serving their application using traditional pages:

In order to support crawlers and users without JavaScript, we needed a rendering system that runs on both server and client. – Twitter

This approach of delivering traditional pages, while still using the “API first” strategy is what I call “Hybrid”. In the diagram below I’ve tried to enumerate the different approaches.



Optimal reuse brings down costs, but optimal reuse can only be achieved when there is a strong architectural strategy to follow. Refactoring code to increase architectural compliance does not bring value to the business directly. It will bring down the cost of change eventually, but the level of trust needed for these decisions is not easily gained.

Further reading

This is not the first post about “API first”. Check out the following links if you want to learn more about it:


I created a deck of 11 slides about “api first” for a presentation I gave on the 26th of November at LeaseWeb.


15 thoughts on “API first architecture or the fat vs thin server debate”

  1. Great article!

    Right now I’m working on an architecture where most of the data comes from batch jobs that run periodically, a small amount is kept in a real-time system, but most of it is kept in special-purpose databases that can answer certain questions with ludicrous speed.

    It is all about reducing latency in terms of customer experience (How is it that it can take 20-30 seconds for a page to load in confluence or most off-brand issue trackers, but only 2 seconds with Github?) and in terms of development time.

    API-first can be a big win if speed is built in from the very beginning, but if you build it as if you could bolt performance on later you’ll discover that you can’t. (Which is why “fast and fluid” Win 8 on a monster laptop with a server-grade CPU, discrete graphics and 32 GB of RAM is less responsive than a slightly underpowered Android tablet such as the B&N Nook

  2. “MVC allows for high reuse in the case you have a front-end / back-end application (in the CMS sense), where customers use the front-end and employees use the back-end.”

    This seems like a stretch. MVC is an architecture strategy, which is a separate issue from code re-use. There are lots of re-use possibilities that aren’t helped by MVC, and are rather orthogonal to it. It’s not false that MVC allows for re-use, but so does virtually every architecture, including “spaghetti”.

    “Typically the MVC approach leads to pages with 200 ms of load time.”

    Are you serious? You’re extrapolating from “MVC” to the number of milliseconds it takes to load a page?

  3. Hi Maurits van der Schee,

    In the case of an architecture like Twitter, would the Presentation Server also keep state via sessions?

    Warmest regards,

  4. @Benjamin: I think they do and I know I would. Thank you for your comment.

  5. @MVC User: Thank you for commenting. I did not claim it was the only way to do reuse, so I think we agree. I know that MVC does not *always* leads to 200 ms of load time, but on most popular server side MVC frameworks it will. I agree that this is a very pragmatic shortcut that should have been explained better. Good point!

  6. @Paul: Thank you for your comment. I would think the speed at Github is realized by applying caching heavily and making use of eventual consistency. But I have no proof to back that up.

  7. Worth mentioning that Twitter dropped their javascript app with direct api integration in favor of hybrid approach. Eliminated a lot of problems with latency. Can not find link right now, but it has happened roughly 1-2 years ago.

Leave a Reply

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