API design fundamentals: usage driven design

Let’s face it:

Until your API has undergone significant real world usage all you have is a bunch of assumptions.

It’s interesting how in a world filled with techniques for figuring out product features with minimal assumptions, we are usually quite ok with guesswork when doing API design.

Now, you will see compelling arguments out there to say APIs are actually a product. And that product will not only outlive your current project: it will also act as a long time reminder of all the failed assumptions you made along the way.

Old school interface design

You want to release a service, so you engage a team of experts, usually leveraging a design-by-committee approach with one or more architecture astronauts who, in possession of crystal balls (or more arcane methods such as canonical model design), are in charge of predicting the future.

And during this exercise you may leverage many techniques but one: asking people what they want. Of course, this is because those specialists know better, so what’s the point in asking? Or perhaps there’s a concern that (oh, the horror), if we ask people what they want, they may actually expect us to deliver it!

If that sounds like a bad idea, it’s because it is.

Who is your target audience? Have you consulted them?

So do your legwork and speak with real life people. Are they knowledgeable about the domain model for your API (ie: do they understand the lingo)? What is their technical background? Are they early or late adopters? Have them go through their major usage flows for your API (these will become journeys and help optimize UX). Have them use a similar service and tell you what their thoughts are. Then and only then consider creating personas to cluster similar profiles.

Obsess over the common case

An API should have one job and excel at it. Add more and complexity will ensue. Fail to make things simple and you get the picture below:

So, after you know your users needs and the one job of your API, you should now know what are the Pareto user stories and make them dead easy. I’m talking don’t-make-me thing easy here.

Is that a product catalog API? Design your GET operations (and their filters) to be as simple as possible, while maintaining it relevant.

Worried about covering that edge case scenario and considering a tweak to make easier? Avoid it if it has any impact on your common case experience.

Evolving an existing API

If you have an API already out in the wild, great. Although this may mean some technical debt (you’ve been doing usage-driven design so this is not a problem, right?), you have a considerable advantage: collectible, real world usage metrics to back your decisions.

As long as you monitor usage, the topic of another post in this series.

Green field APIs

Starting from scratch is usually seen by developers as a great thing — “hey, no legacy, no chains holding us back”. Problem is, with no legacy comes no context. So if everything is new, if you haven’t still released a product, much less an API, how do you reduce the amount of assumptions you do in the process?

In this case, besides leveraging the very same inception techniques you would on a new product, there’s a couple more things to consider:

  • dogfood: if real world usage is the driver for good design decisions, then try as much as you can to use your APIs when building your products. I have seen API teams take over their corresponding UIs to be perplexed with the complexity of their interaction;
  • baby steps: in both API design (less is better for evolution) and in terms of release: implement, harden (through dogfooding) and incrementally release. If you can pull a beta or a hackathon before your public release, even better;
  • design for evolution: yet another topic for a full post, but TBH this guy already covered this subject masterfully;


This post barely scratches the surface and calls for a follow-up about inception techniques one can use for API design. But if there’s one single thing to keep from this (and from this whole API design series), it’s this:

It’s a good idea to ask customers what they want before building something. That principle applies to APIs as well.