Building Quality APIs by Managing Complexity as We Go

Quality APIs don't happen on their own. We know this from experience. Bad code doesn't get better after we run git commit, and poor design choices don't improve while we're out to lunch. So if we want to design and build better APIs, we have to be intentional about how we do it.

We've all used poor-quality APIs. They're hard to use. They're difficult to understand. We had to spend extra time digging through documentation and piecing together clues to find the data we needed. If an experience is bad enough, we went looking for a better API. We want to try to avoid this for our APIs if we can.

I recently released an ebook called API by Design that's about building quality APIs. Actually, it's about the opposite of quality—complexity—and how, if we're ever going to improve the way we design APIs, we're going to have to find a way to manage complexity as we go. Otherwise, we're left to hoping that our decisions won't lead to complex, hard-to-use APIs.

If complexity gets bad enough to frustrate us or slow us down, we've waited too long to deal with it. Maybe we cut a few corners as we went or took some shortcuts in the beginning, thinking we'd come back and clean things up. But we often get busy and never find the time. Those tiny choices we make to increase tech debt are high-interest loans. They grow and compound over time until they put us over our heads in debt. Eventually, it becomes easier to rewrite the code than to change what's there.

This is especially true for APIs because APIs are good at hiding complexity. We can't change them however we want because we don't want to break existing clients. So we have to be cautious with how we evolve them. We have to work around what's there, adding and never removing. Without a plan to deal with the accumulation of features, we risk creating a poor user experience.

We need ways to manage complexity as we design and develop our APIs. We need to know how much complexity we add with every API change.

If we can measure and catch complexity early in the development process, we can design and build quality APIs. Managing complexity goes together with managing quality.