Principles of Designing & Developing an API Product [Part 2 of 4]

June 13, 2019 Caroline Hane-Weijman

We are Caroline, David, Francisco —a cross-functional product development team that worked together at Pivotal Labs, a product development consulting company. This is the second part of a four-part blog series to share tactical learnings we encountered when developing a product where the interface was a set of APIs for other developers to consume in order to meet their own business and user needs.

In our previous blog post we shared our learnings for foundational principles and concepts of designing and developing API products. In this blog, we share the process we took to design the APIs to meet business and user needs.

Discovery and Framing

At Pivotal Labs, we typically begin a product engagement with the Discovery and Framing process: a set of activities that helps a team understand the users and evaluate possible solutions and minimizes product and development risk for the first release. We typically begin by exploring the problem space through user and stakeholder interviews and market research, to validate and narrow down the problem space for the first release (Discovery phase). We ideate and prototype our ideas for that first release, test those prototypes with real users and start development when we have a higher level of confidence in the initial set of features (Framing phase).

This process requires a balanced team of a Product Manager, Product Designer, and Engineer so that the problems and solutions are considered through the lens of the business priorities, user needs, and technical feasibility. Including the three disciplines from the start of the project allows the team to deeply understand the problem space and build a solution that works.

Identifying Users and Approach

As in our previous blog, we’ll use a hypothetical business case to help anchor the discussion: A product team working for a “Payment Company” is building an application that processes payments, developing features that allow an online retailer (e.g., “Sock Company”) to take payments from a customer (“Sock Buyer”). When the Sock Buyer purchases a pair of socks online, they provide personal information and payment information to Sock Company. The APIs we developed are used to communicate the relevant information from Sock Company’s software system to Payment Company’s software system in order to process the payment.

The functionality that we developed as a team was defined by the needs of the business and its end customers. However the direct users of our API are the developers working for said business. We needed to first define feature priorities by solving for the business user and end user needs (e.g., online “Sock Company” business + “Sock Buyer” needs). Then we needed to consider the developers consuming the APIs to define the API design and experience (e.g., developers working for online “Sock Company”). There were therefore three sets of users that defined feature priority and experience of our API.

We recommend approaching the Discovery and Framing (D&F) process in two phases to address our multiple users’ needs. Assuming a three-week D&F:

  • Week 1 - 2: Define features and priorities based on exploring the needs of the business consuming APIs (User #1) and its end customers (User #2). Recommend a balanced team of a Product Manager, a Designer, and an Engineer.

    • Stakeholder and business user interviews to identify the business priorities, needs, and constraints

    • User personas representing groups of business users to illustrate the users’motivations and needs

    • Service blueprints and workflow diagrams for target user personas

    • Identify features and prioritize based on target user personas

  • Week 2-3:  Design the API experience based on exploring the needs of developers working for this business (User #3), as well as do technical discovery and setup.  Recommend an expanded balanced team of a Product Manager, a Designer, and two to three Engineers.

    • Interview developers (engineers on the product team should be part of these interviews!)

    • Based on features and developer interviews, create API mocks of endpoints with requests & responses (using a tool like Stoplight with Postman)

    • Validate initial mockups with developers

At the end of D&F, the team can then review both feature prioritization and mockups of APIs.

Phase 1: Understanding Product Needs

For the initial D&F, we primarily interviewed business users (e.g., Head of Product and Pricing at “Sock Company”) that would be paying for our functionality and could represent the needs of their own customers. Similar to how we create personas of end users, these stakeholder interviews helped us create pseudo-personas of business segments to understand their needs and the opportunity they represented for our own business.

Once we understood who the primary user was, creating workflow diagrams helped us understand how an action starts from the customer, touches the business, and reaches our payment API. We used this to narrow down the initial feature set based on capturing the most common business use cases, feasibility, and ability to capture the market.  For example, one feature that was prioritized was the ability to take fixed amount payments every month, as that served the biggest use case for businesses. Another feature that followed was the ability to offer customers installment plans for their purchases.

Once we had a list of features, we stack ranked these features with a card-sorting exercise and identified our first set of release markers that would allow us to quickly deliver value and learn from our beta users.  

Phase 2: Designing a Useable Experience

For the second phase of the D&F, we interviewed around eight developers. These exploratory interviews were useful to decide what we knew and needed to validate, or didn’t know enough about and wanted to understand. The output from these interviews gave us a set of guidelines that developers use to evaluate APIs in the same domain space, how they think about solving business problems, their mental model for defining the objects and resources needed to build specific features. We used all of the insights from these interviews to generate ideas for how to structure our endpoints.

We did a combination of exercises during the developer interviews:

  • Exploratory interviews 

    • Focused on recent behavior and interaction with other APIs in a similar domain (e.g.,  How do they evaluate, compare, or use an API?)

  • Prompted developers with a business scenario and asked them to write down:

    • Resources they anticipated existing/being created

    • Expected endpoints based on specific actions. We recommend also doing the reverse: show mocked endpoints and ask developers, “what do you expect to happen with this endpoint?”

Exploratory Interview Questions:

Once we had completed this round, the result was five sets of endpoint design principles that we dot-voted on to pick our direction (refer to our first blog post for details on nested, non-nested, and top-level resources design principles).

  1. Nested Resources - consistent pattern, only consumer top-level resources

  2. Nested Resources - consistent pattern, both consumer and subscriptions top-level resources

  3. Nested Resources - inconsistent patterns

  4. Non-Nested/All Top-level Resources

  5. Non-Nested/All Top-level Resources, except for payment_method which was nested under consumer

Validating Solutions

Once we had a direction for how to design the endpoints, we conducted another set of user interviews, this time to validate that our API designs were intuitive and matched their mental model. We used a similar task of showing the developers an endpoint, asked them what they expected to happen, showed them our mock response, and observed their reactions. This allowed us to identify any outstanding pain points and see how usable our solution was to them. While there isn’t a presentation layer to the interface, the endpoints and responses are a representation of expectations, and user testing the task gave us confidence to move forward with our solution.

Key Artifacts

While all projects are different, we recommend considering these key activities as you design your API:

  • Create developer and company personas → This helped us identify the right segment of users

  • Map user journeys and pain points → This helped us define criterias to generate and evaluate solutions

  • Identify scenarios and use cases → This helped us define tasks

  • Prioritize features with a card-sorting exercise → This helped us define the backlog

  • Interview developers for their API development experience → This helped us define our API design

  • Create prototypes of APIs and conduct usability tests → This helped us test assumptions before building

In this blog post, we’ve covered the key methods you can use to identify and illustrate the conditions in which your solutions are evaluated. These user-centered design methods allow the team to have a deeper understanding of how to build a solution so that it has a higher chance of meeting the business and user needs.

Hello! We are Caroline, David, Francisco - a cross-functional product development team that worked together at Pivotal Labs, a product development consulting company. Pivotal Labs work with our clients as an integrated team, sitting side-by-side, to build & deploy digital products while enabling our clients to learn lean, user-centered, agile software practices that they can use as key capabilities on an ongoing basis within their organizations. 

This blog is one of our 4-part blog series on Designing & Developing APIs:

About the Author

Caroline Hane-Weijman

Caroline Hane-Weijman is an Engagement Director, East Area Lead, based out of Pivotal New York.

The goal of digital transformation is outcomes, not engineering
The goal of digital transformation is outcomes, not engineering

Organizations should avoid taking on unnecessary engineering projects, especially when that work is focused...

A Balanced Approach to Security
A Balanced Approach to Security

How to strive towards this balanced security team and achieve great (and secure) experiences for all.

SpringOne at VMware Explore 2023

Learn More