Yep, We Should (Almost) Always Build An API

Last week I published a post entitled Opinion Time: Should Developers ALWAYS Build an API?. I got quite a bit of useful feedback on that post, and so I decided that I needed to publish a followup post so that I could parse and interpret all the different opinions you lovely readers gave. I was expected something of a heated fight, or at least a good match, but it turned out to be a slaughter. One side clearly and convincingly won the argument: almost all of the commenters on the original post agreed that building an API is a good idea, most of the time.

A questionnaire with "Yes" "No" and "Maybe" answers, where the "Yes" answer has an X in the box.

What's An "API" Anyway?

Before we can even ask if we should always build an API, perhaps we should figure out exactly what that means.

API stands for Application Programming Interface, a wildly generic term on its face. When I wrote the Opinion Time post, I was thinking of an API as being a separate, stand alone service or data store which could be consumed by another application; commenters have rightly pointed out that my definition of an API was far too narrow:

...I think that in this case you're incorrectly thinking that your two opinions disagree with each other. They don't.

Yes, you want separation of concerns. You're right. That is "always" good.

Yes, you want to avoid YAGNI. You're right. That too is almost "always" good.

But in both cases, there is a matter of how far you push it.

Does your "API" have to be a separately deployable HTTP endpoint? Could your API just be a second set of controllers in the same application?

Perhaps your "API" is as simple as a "repository layer" in a separate class library in the same solution as your MVC UI site.

-- Travis Laborde

Travis brings up another good point: we want, need, separation of concerns in our apps. In a world where no single idea can be always good or always bad, separation of concerns is one of the few concepts that is consistently valid and accepted. So wouldn't building an "API" (for whatever that means) be a good thing most of the time?

Experience Trumps Theory

Another commenter had a personal experience that led him to the same conclusion as Travis:

At one point I would [have] thought that we do not always need an API for every application. However recently I have a project of moving an existing application without an API have it interact with a new system/front end. Now the task of writing the API to fit within the existing structure of the old program and interact with the new system/front end has become quite a task.

For me I will always want this separation using an API.

-- James Bridenthal

In fact, quite a few people had personal experiences that led them to the same conclusion:

Just this year, our organization decided to "open" our systems up to a third party for the first time - in terms of exposing an external API.

What we've discovered is that, even where we don't have the exact right APIs already developed for this third party, the systems which already have the API separation are proving trivial to amend to fit the requirements. Whereas the monoliths (of which we have several) are proving problematic to provide APIs for.

-- Damien

Need To Be Flexible

A couple people pointed out that the real reason we would to build an API was flexibility, including the potential to refactor to new technologies as they become available:

I am pretty firmly in the API ALL THE THINGS camp. In my experience, you can never predict when you may be asked to expose functionality you've built to something other than the original application. Just today, I was approached about exposing functionality ... from an app written four years ago to a third party.

Building with an API from the ground-up allows that future flexibility. As others have noted, adding an API layer after the fact is almost always going to be more difficult/time-consuming. It also helps to ensure that separation of concerns is baked in to the architecture.

-- Brian Griffith

Solve A Problem, Not All Problems

One commenter preached caution when deciding what standard to build your API against:

I second David Fowler: "If you have an abstraction with a single implementation then you don't have an abstraction."

As long as the API has only one consumer, it's entire job should service that consumer. Make it REST-ish, sure, but don't bend over backwards to meet some arbitrary ideal standard. Need to use POST as an RPC (Remote Procedure Call)? Go right ahead. Clean it up when you need to.

-- Steve Cleary

An Anecdote

All of this was summed up beautifully by this anecdote:

Years ago, in my bedroom, I had a portable TV with a DVD player built into it. It cost more than buying a similar-spec TV and a standalone DVD player, but I was tempted by the convenience.

Then I moved house and got a bigger bedroom, so I wanted a bigger TV. Which meant I had to buy a brand new DVD player, too.

-- Mark Rendle

Summary

In short, whether or not to build an API for your system is a function of the complexity of that system. For trivial apps an API is probably not needed and can be discarded as cruft. But as the complexity increases, the likelihood that building an API will make your system easier to maintain and simpler to change increases rapidly.

In my particular case, the API for our system was absolutely necessary, because it's a non-trivial application and we will need to make changes in the future. Not having an API layer would make such changes more difficult, and having separation of concerns be a feature of the architecture will alleviate our project's growing pains.

I feel confident enough that I can now present the following argument: the only apps that don't need an API of some kind are trivial ones. Otherwise, favor building an API for all your apps unless mitigating factors make that impossible.

Of course, now we need to define what "trivial" means. Perhaps there needs to be another Opinion Time post? :)

Thanks for all the comments, and Happy Coding!

Matthew Jones

Matthew Jones

I'm a parent, a husband, a geek, a web developer, and a speaker, in roughly that order.

Read More
Yep, We Should (Almost) Always Build An API
Share this