Why a Clean API is Critical for Any Public-Facing Web Application

Adrian Sud, Web Developer

For most web projects, building an external or internal API is the last thing that happens, if it happens at all.  You envision the user interface, and design the data model required to produce that experience.  You start building the interface, wiring it to the model as you go.  Eventually, someone might think of setting up a public API, be it before launch or some time later. So you quickly provide accessors to whatever functions just happened to be available.

This is how we end up with APIs that can be more convoluted and difficult to use than the web application they were built for, or that are missing functionality to protect the system from bypassed business logic. This kind of “afterthought API” forces your whole system to become bloated, more complex, and more difficult to maintain, when in actuality an API should be the guiding principle toward making our applications as streamlined as possible.

Regardless of whether you expose an API to third parties, it pays to have one in mind from day one of development. If you look at the Twitter API, it is extremely clear that almost every function they might use internally was designed to be used externally as well—it isn’t a stretch to say one could replicate the entire Twitter site using their own RESTful API calls. This means that their developers and architects put a lot of thought into what functionality occurs at the atomic level and what does not. For example, a twitter post may contain geographical information, retweet information, client information and timestamp, any number of other things that might require pre- and post-tweet processing, but all of this is treated as one atomic operation in the API, and I would wager a lot that this is because the process is functionally atomic in their initial “Controller” code as well.

In the general web development community I often see the “Model-View-Controller” or MVC paradigm being used, but the process I usually see happening spends a lot of time worrying about the Model or data structure, and a lot of time worrying about the View or User Interface, the Controller or business logic handler being mashed together in order to appease those two. But designing with a public API in mind, requires you to spend more thought on designing the Controller, in order to fit not just your current UI, but all possible interfaces. This means a “clean API” is no more or less than well organized, well defined Controller code, and that is crucial to any web application’s future extensibility and maintainability.

Photo credit: http://nowsourcing.com

Share and Enjoy

•