Focusing on Problems When Defining a New API

I am working on version 2.0 of the content API I am using as part of my work across Postman Open Technologies. It is a little meta, but I have an API for managing the content I produce and then distribute across the blog posts, videos, and books I am producing. I am using the API to help standardize and power the storytelling across my own work, but continue leveraging to do the same across my team. I’ve been using a half-baked version 1.0 of my API to guide my work for the rest of the year, but I am looking to continue adopting our internal approach to API-first at Postman as part of how I work externally as my team’s operational, demo, workshop, and community APIs. To kick off this effort I am sitting down with Bruno Pedro (@bpedro), the product manager helping lead API-first within Postman, as well as our public API strategy, and beginning to walk through his API playbook.

The first step of the API playbook as ideation. Before we move into building our strategy, we needed to ideate about what this API would do for consumers. We fired up a Postman team workspace, and got to work ideating using an outline on the workspace overview. I immediately began rattling off the solutions this API would provide. Bruno patiently paused me and said that we should focus on problems before we plan any possible solution. Bruno’s focus on problems reminded me of how I easily slip into API solutionism and get right to work demonstrating how APIs will fix anything without ever actually describing a real world problem. This is why I am following Bruno’s playbook instead of mine. I move too fast. I make the same mistake many API developers make, moving from zero to building something as quick as possible without ever conducting the due diligence and engaging in the critical conversations that will actually inform my API design. I followed Bruno’s lead, and began ideating on the problems I’ve seen across specifically my own approach to producing and scaling content, but also my teams.

Once we ideated a bit about the problems we were looking to provide an API solution for, we began moving into the strategy phase of esigning our API, focusing on who will be involved in producing this API. Right now, for sake of simplicity and velocity, Bruno and I are going to be the only stakeholders. We will widen this involvement as we get a beta version of our API ready, but at this stage we are looking to streamline the process. I have already been using my API for a year and Bruno is an expert on the process we are looking to apply and document, so we should be able to cover some serious ground with just the two of us. In our next meeting I’id like to spend a little more time on the participants aspect of defining our API, for the sake of the process, but then continue moving towards defining our strategic goals, who the target personas for the API will be, and what our jobs to be done are.

I wish I had more time over the last year to spend aligning my approach to the API lifecycle with Bruno’s. I have been digesting all the great work he is producing internally across Postman, weaving some learnings into my approach, but due to the number of customer conversations I was having, the Breaking Changes interviews I have been doing, and the project work across my different API specification projects, governance, and supporting the recent v10 release–I just haven’t had the time I needed. Not anymore. I will be spending several hours a week learning Bruno’s approach to delivering APIs, aligning it with how we are doing APIs internally, and producing content for our customers and the community to follow when they produce APIs. One thing Bruno and I agreed upon was that whichever API we moved forward with his playbook, it had to be real. So it made sense for us to apply the process to developing an API that would help us manage, scale, and iterate upon the process itself. This way, as we continue to standardize how Postman delivers APIs, we can share the knowledge with our customers, continuing to maximize the feedback loop we have across our large customer base to iterate and evolve the process. What I really like abou tthis is that what are practicing what we preach while providing the ultimate guide to delivering APIs—-using an API-first way.