Translating user benefits into API capabilities

This post was originally published on the Postman blog as “Translating user benefits into API capabilities”. The original content was professionally edited.

As part of my ongoing work designing the Postman Open Technologies Knowledge Base API, I have identified most of the technical characteristics of the API. Now I need to define the capabilities that the API will offer.

I’ve been following our internal API design playbook, which covers the strategy, definition, validation, and specification. I already finished the strategy step by documenting the user personas, interviewing potential API users, and identifying the API architectural style. I’m still in the API definition phase, where I’m defining the API’s capabilities. When I say “capabilities,” I’m referring to the functionality that the API will offer to fulfill the needs of potential users. A capability can be reduced to a feature or a set of features, depending on its complexity.

I reviewed the potential benefits of the user personas that I had previously identified in order to “work backwards” from what users value to the features that I wanted to implement. This process is best described in the book Working Backwards by Colin Bryar and Bill Carr. The book’s authors argue that you should identify and communicate your product benefits to potential customers as early as possible.

The “working backwards” approach is advantageous because it makes it easy to pitch your API to new users. For example, one of the identified benefits for API designers is “comparing an API design with the common practice across verticals.” I can use this insight to pitch the Knowledge Base API to other API designers while referencing the exact benefit that was identified by someone in their same cohort.

Since my goal was to identify the API’s capabilities, I summarized the list of benefits into groups. Each group lists benefits that are identical or belong to the same category, independently of the user persona. For each group of benefits, I drafted a capability that would deliver what users need. An example of a capability I identified is “returning a global report of API-related statistical information.” This capability is related to the identified benefit because it lets API designers understand what the common practice in the industry is. By retrieving a report of API-related statistical information, they’re able to compare an API design against the common practice across verticals.

After identifying all of the API’s capabilities, I documented them. I then shared the list with the API’s stakeholders—business owners, potential API consumers, and product managers—and asked for a high-level validation. Obtaining feedback from stakeholders helps me know if I’m heading in the right direction before I implement the API. In this case, I learned that the focus is on letting users retrieve statistical reports, and offering those reports in HTML and PDF formats is mandatory. This insightful feedback helped me narrow the scope of the API.

In summary, there are many advantages to being able to understand, document, and communicate the benefits that your API brings to users. First, you can reference each benefit when you’re discussing your API with potential users. Second, a clear understanding of the API’s benefits gives you a tangible indication of why you are building the API. You can then translate benefits into capabilities and, from there, define the functionality of your API. By following the method that I suggest here, you’ll be aligning your API definition with the needs of users. In the end, your API will have a better chance of succeeding.