The Most Important Step in the API Lifecycle

I learned the hard way how to design useless APIs. I still remember how I would spend most of the time making sure that my API was mapping the underlying data model. Or, how I would obsess over the details of the API definition. Fortunately, those days are long gone now. Now I know that those details are meaningless to consumers if the API doesn't fulfill their needs. Really, what I was doing was designing an API for myself, not the consumers. Is this scenario familiar to you? I suspect you've been through this a couple of times at least. Getting out doesn't have to be complicated. Read on to see how I did it.

This article is brought to you with the help of our supporter, Naftiko.

Naftiko is a platform that helps organizations manage their technical assets as business capabilities. It provides a central space where teams can define and discover what their services can actually do. By moving the focus away from raw API operations, Naftiko helps engineering and product teams work better together.

It was 2006 or 2007, I can't remember exactly. I was working on a project for a big book publisher. My goal was to create an API so that warehouses, printing companies, book shops, and other partners could integrate with the publisher. The API style of choice at the time was SOAP, and along with it came the willingness to model everything around objects. Needless to say, it felt perfect to me. I mean, how else would I design an API about books, right? Right? I made an inventory of all the existing objects and all the possible actions between them. Then I implemented the API and even did a full battery of end-to-end tests. Everything was perfect. Until I shared the WSDL (the SOAP equivalent of an OpenAPI document) with a partner. Their questions and support requests started coming in. "How do I get the author and publisher IDs so I can create a book?" was something no one except me could understand. Partners would have to check if the book author and publisher already existed to get their IDs. Or, they would have to create them instead. This happened because, to create a book, you'd need to send in the author and publisher IDs as numeric parameters. From the consumer's point of view, it didn't make sense. I obviously was oblivious to that. How could I not be?

Talking with API consumers is something that would have helped me be aware of their needs and desires. By first understanding users' problems, you can learn what solutions they find valuable. You learn how they go about their days and what tools they use. You learn what the things they value the most are. If you do it on a continuous basis, you'll gain a deep understanding of your audience. And that will certainly lead to better API designs. However, that alone won't guarantee that your API is fully aligned with your consumers. To get there, you need to go through the most important step in the API lifecycle: the API Design validation loop. API Design is, itself, a lifecycle step that decomposes into several blocks. It starts with ideation, then strategy, followed by definition, validation, and, if there's alignment, specification and implementation. Notice that there's a condition to move forward. "If there's alignment." If you and your consumers aren't aligned, you get to repeat the API definition. Each time you pass by the validation loop, you put the API closer to what they really need, not just your own ideas. So, how do you go from theory to practice? What exactly do you need to implement an API Design validation loop? Keep reading.

Saying that you have an API Design validation loop is one thing. Executing it properly is something else. The goal of the loop is to make sure that it only ends when all the involved stakeholders agree with the API definition that you’re proposing. That’s all you need to understand to implement it. You can create a fully manual process, automate all the steps, or just some of them. Let’s look at a couple of examples to see what your options can be. Take, for instance, a company that has just one API and a handful of partners. There are changes every couple of months or so. In this case, it probably doesn’t make sense to invest in building an automated process. Having meetings with the stakeholders to present the new design might be just enough. On the opposite side of the spectrum, imagine a team serving several APIs inside a large enterprise. They have hundreds, or perhaps thousands of API consumers. Any change, even a small one, can make the API difficult to integrate with. In this scenario, having a feedback management system in place makes sense. Trying to manually capture the opinions of hundreds of consumers would be a recipe for failure. In any case, having a tool that lets you generate and share an API prototype is a must. People usually like to try things out before sharing their feedback, right?

And the longer they spend testing your API prototype, the longer you’ll have to wait. API Design validation easily becomes a bottleneck, especially when many stakeholders are involved. Asking for feedback on a large change means opinions take a long time to arrive. On the other hand, splitting a large change into smaller chunks means navigating the validation loop multiple times. While maintaining a feedback system might seem easy, the cost of delayed API implementation is high. Multiply this delay across all teams and stakeholders, and the process quickly gets out of hand.

That’s why API Governance is so important. But that’s a topic for a different time. What matters now is that you have two options. You can continue to implement APIs without knowing what consumers really need. The risk with this approach is that you’ll have to re-design and re-implement your API every time consumers complain. Or, you can just adopt the API Design validation loop and implement exactly what stakeholders care about. Here, the risk is that you end up spending too long in the loop. So, what would you prefer?