The Butt Ugly Weblog

APIs and Architecture

Many geeks love boxes. And once you got that magic title, "Architect", in your job description you start loving them even more, 'cos that's what you get to do all day. It's really nice to design scalable architectures and think about how data flows between modules and how to tweak the system and argue and finally commandeer a large army of coders who build your dream. It's fun!

But there's a small problem. Quite often you also need to design an API - an interface through which other people can use the wonderful framework you designed. And here lies a danger: if you design your API after the architecture design is done, your API will reflect the internal design of the system. And that, in turn, means that if you change your architecture, you will have to change your API as well. Which breaks the promise you've given to the people who are accessing your system through the API. Unlike humans, who can figure out if a button has changed place on an HTML page, computers get really iffy when it comes to argument ordering and types. In a word, the API becomes brittle.

So the right thing to do is to design the API first, and then match the architecture accordingly. This way the API is not dependent on changes you do under the hood. This is much harder to do, and much less fun, but it will create you a better system in the end - because no matter how beautiful a thing you've designed, if it's a pain to use, it won't get used.

Love the boxes. But not too much.