You are here

How to Incorporate Feedback Loops Into Your API Design

‘Move fast and break things’ might be a good philosophy for web app development but it’s not so simple with API design. Client apps rely on your APIs. You can’t just release a radical new version every few months that breaks all previous integrations. Lorinda Brandon over at the Capital One blog shows you how to bake feedback loops into your API design so you can incorporate the best insights of the lean startup methodology without moving so fast you break your clients’ apps.

Why Feedback Loops?

Why would you want feedback loops? They allow you to plan capabilities in advance so you can think strategically about release plans and your partners. Second, you can gather feedback for your roadmap and planned features, which you’ll be able to change more quickly because you’re not already committed to an API design. Lastly, your API clients will be more invested in your release cycle because they have some control over its direction.

So why would anyone not want feedback loops? Well, they have a few downsides. You have to expose your ideas to the public to get feedback. And you’ve got to move quickly on feedback or be prepared to see disappointed clients. Moving quickly has its own disadvantages. Quality gets sacrificed for speed.

But the plus side is that you write an API that you know developers actually want to use.

How to Get Started With Feedback Loops

There are any number of feedback loops you could incorporate into your design process. Lorinda suggests a feedback loop in which you have four parts: release/versioning, developer feedback sessions, publicly available prototypes and beta-invite only releases. You can see the dependencies in the following picture.

Developer feedback sessions

It’s a good idea to have developer sessions where you can just discuss potential ideas for API features even where ideas are not well-developed. Lorinda recommends having no more than 30 people for any session and including diverse participants, such as enterprise devs, product managers and biz dev people. Make sure someone takes notes and that all ideas get a fair hearing.

Publicly available prototypes

Lorinda recommends following up focus group sessions with a prototype of the first API version. The motivation here is to move from idea to reality, creating something that developers can test with mock data. You can then get feedback on the interface from potential clients.

Although this is just a toy API, be sure to make the API design as clean as possible. You don’t want to put potential users off the product before it’s launched. On the other hand, make sure you provide enough mock data for developers to have a sense of how your API will perform under a heavy payload, even if that’s not complimentary to you.

Lorinda also strongly advises providing draft documentation with the prototype. The documentation is part of the API and needs feedback too.


At this point, if you have no major security hangups, you can make a beta release available to the public. For the more security-minded, you do an invite-only release before a general release, which gives you another chance to garner feedback.

Lorinda recommends being selective in who you grant access to. Size up the community you want to reach with this release and make sure you stick to it in the invitations. Think too about how you’re going to reach this community. Do you want to have a signup form or do you want to privately contact developers involved in previous iterations.

Once you’ve got your community together, give them a set amount of time to play around with the beta release. Make sure give yourself enough time to make changes after feedback but have a target date for general availability.

Lorinda concludes by stressing that the above tips are supposed to help you avoid versioning as much as possible. But where it’s unavoidable, she recommends maintaining support for multiple older versions and sharing information early with clients so they have plenty of warning for any backwards-incompatible changes in the next version.


Be sure to read the next API Design article: 7 Rules to Follow for REST API URI Design

Original Article

API Design Using Feedback Loops