Saturday, November 05, 2011

API-First Development

A while back, REST advocate Juergen Brendel twitted:
API-first development: Modern dev. must consider multiple clients. Think about your REST API first, then add front end.
I retwited him because I can't agree more. In fact, even if there is a single client I'm convinced API-First development is a winning approach.

I've been involved in two three API-first projects, all very different in term of domain, size and technology. But in all cases, things turned out pretty well, and, in fact, way better than with traditional approaches to web development.

Clear responsibility delineation - When an API gets defined, client and server responsibilities become easier to define. The API becomes the guardian of this separation of concerns, as any temptation to make concerns of one side permeate to the other will either be impossible or at least extremely cumbersome. The API will resist almost naturally to desires to pervert it.

Better maintainability - Server-side front-end generation usually ends up in a pretty ugly mess where presentation concerns get mixed with service concerns. Even when following the MVC pattern, the sheer fact all artifacts are contained within the same project space opens the door to nasty transfers of responsibility between layers. An API is a contract around which clients and server can evolve harmoniously.

Client liberated - Front-end developers can use rich internet application frameworks and work on a clear interface with the back-end instead of getting constrained by a particular technology and having to deal with data transfer objects they don't fully control and which may change unexpectedly.

Test what matters most - This revolves around my previous rants about what's really important to test. When you expose an API, you can fully test your system as it is experienced by its different clients. There is no need for in-browser testing gimmicks. A simple HTTP client allows you to guarantee that the back-end is performing its duty and offering the front-end the features it needs. And that's what matters most.

Ninjas only - This point is a little harsh but here we go: API-first tolls the bell of tag soup developers. This category of developers, not skilled (or experienced) enough to be doing pure server-side development nor pure front-end one, is not needed anymore. Developers building clients for a server API are experts in their domain, be it HTML5, JavaScript, Flex, Android, iOS, Phonegap or whatnot. They can't rely on "the back-end guys" to pre-chew their job and are fully in charge of what they do.

In API-First development, the time you reach the point of trying a first connection between an actual client and the server is an exhilarating moment. Sure you've been testing the back-end for a while with a simulated front-end, but when they both connect for the first time, it's party time! And amazingly, things work very well right away, all thanks to a well defined API.

Before closing I should mention a downside for which I haven't found a satisfactory answer yet: against what back-end should client developers work? It is sure easy enough to expose a development-grade server to use while developing the front-end. But it's not always practical. A local server is an option, a client-specific stub is another one. Or maybe a state machine simulating the server API and allowing the front-end developer to change its state at will to easily simulate test scenarios?

So, what's your experience with API-first development? Any blazing success or horror story to share?


Juergen Brendel said...

Fully agree on all points.

About your concern that it's not clear what the front end developer should test against: I believe it has to be an HTTP server, not a stub. Setting up a local server usually isn't difficult and if something prevents it then this should be solved until it is difficult.

The reason here is that interaction via an actual HTTP server can be different and surprising. Proper handling of HTTP headers and status codes needs to be done even on the client side, so I would suggest to test against the real thing.

And ideally - while surely not always possible - not just a local server, but a server that resembles a production setup (with all caches and other layers fully setup). That's again because some headers are re-written or disappear, status codes may change because of funny intermediate layers, etc. If a full production setup is done well, this shouldn't be too much of an issue, but you never know.

David Dossot said...

Thanks Juergen, you made a great case for coding front-end against "the real deal".

Dom Farr said...

Interesting. We have gone through this (the hard way) at qmetric. Building the classic three tiered web application, only to find it became a giant mess.

If your tiers can blend, because they are part of the same project, they will find a way. Spring only helps with this. It is just too easy to sneak in an annotation that allows domain classes into higher tiers, when a refactor should have been performed. Before you know it, ball of mud. We are dropping spring and single web app style for these reasons.

Forcing separation of through language agnostic messages is a great way to keep it clean. It allows teams with different life cycles to run at their own pace. Reduces the requirement for heavy selenium testing as the only option.

Twitter also went through this progression from 3 tier to api.

David Dossot said...

Thanks for the great feedback Dom!

Nikos said...

Great points! Apifirst means you can roll out your apps with more flexibility + if you have an api you will find it much easier to get 3rd parties on board with your data.