3. Identify Digital Capabilities

When we buy a product, we essentially “hire” it to help us do a job. If it does the job well, the next time we’re confronted with the same job, we tend to hire that product again. And if it does a crummy job, we “fire” it and look for an alternative.

Clayton M. Christensen, Taddy Hall, Karen Dillon and David S. Duncan

APIs are the most common manifestation of digital capabilities as they power web and mobile apps, partner integrations, and workforce solutions. They allow the casual or expert developer to take advantage of data, business processes, and internal systems programmatically to produce desired outcomes. Organizations must develop the skills to identify digital capabilities (see Figure 3.1) and use them to shape the API design to help users produce results.

The ADDR Process starts with defining the digital capabilities necessary to deliver customer outcomes. It also elaborates on the specific activities and steps needed to deliver the outcomes, prior to designing the APIs.

This chapter introduces the concepts of digital capabilities, how they related to APIs, and outlines an approachable method for mapping requirements into a format that identifies necessary digital capabilities. These digital capabilities are then used to inform the design of product and platform APIs.

Ensuring Stakeholder Alignment

As discussed in Chapter 2, API design is a communication process. It communicates the digital capabilities offered by an API to external and internal developers across team and organizational boundaries. Those outside of the API producing team that will consume the API cannot, and should not, be required to read the actual code of the API to fully understand how it works. In fact, external developers may not have access to the source code at all. Therefore, the API design and any subsequent documentation should strive to communicate with developers in the simplest way.

Effective API design incorporates the needs of customers. In this context, customers are defined as a segmented group of developers and end-users whose experience will be shaped, for better or worse, by the API design. Keeping an API design in alignment with customer needs helps to deliver a great user and developer experience.

An API design that misses the mark will deliver a poor experience, often requiring significant changes that will break existing integrations. Once an API has at least one integration in production, it is very difficult to convince internal or external teams to spend the time and money necessary to upgrade to the next version of an API. This leaves no room for an API design that breaks existing integrations. Therefore, arriving at an API design that meets the needs of customers requires focused effort rather than guesswork.

Unless the organization is small enough to support direct communication between developers and customers, there are often multiple roles involved with product definition: product owners, product managers, business analysts, software analysts, and account managers to name just a few. These roles represent the needs of the customers. An effective API design includes input from many roles across the organization, not just the technical details of how to push data in and out of a data store or legacy system.

It is also necessary to create alignment between stakeholders and the development teams responsible for implementing the API. If the API lacks business context, it may meet the needs of customers but lack sufficient factors to meet business goals. If the API lacks a customer context, it may meet the needs of business but fail to deliver the desired outcomes of customers. If it lacks both, the API will serve no real purpose and efforts will have been wasted. In the ADDR Process, digital capabilities are used to create alignment between business, customers, and technology to avoid these negative consequences.

Principle #1: APIs should never be designed in isolation

Collaborative API design is essential for a great API. Each person contributes their experience and can leverage their strengths and skills as part of the API design process.

What are Digital Capabilities?

Business capabilities describe the enablers an organization brings to market. Examples of business capabilities include consumer product design, product manufacturing, and customer support.

Digital capabilities are assets that turn desired outcomes into reality through automation. They offer the workforce, partners, and customers the ability to interact with the organization digitally. Digital capabilities may take the form of one or more technology solutions. Examples include REST APIs, Webhook-based asynchronous APIs for integration, SOAP services, message streams, and bulk data exchange through a nightly, weekly, or monthly file-based export process.

Reviewing the digital capabilities offered by an in-house or competitor’s product or service provides greater insights into what the organization values, including the market segments they address.

A digital capabilities portfolio is the collection of digital capabilities offered by a product or organization. For organizations building a platform to connect two or more parties within a marketplace, the terms digital platform and platform capabilities may be more familiar.

While digital capabilities may be mapped to business capabilities, they operate at different levels of concern. Business architects define business capabilities, such as customer service, and may associate key performance indicators (KPIs) or objectives and key results (OKRs) to track growth. Digital capabilities focus on producing outcomes and include the activities required to deliver the business capabilities of the organization. Business capabilities describe the “what” of the organization; digital capabilities describe the “how”.

Table 3.1 provides an example for a typical project management application to demonstrate the differences between digital capabilities for a project management application and how they may be realized through a REST-based API:

Notice how the digital capabilities are written with a focus on customers and their desired outcomes. The choice of API design style, such as REST or RPC, is not explicitly part of a digital capability but rather a part of how the digital capability is manifested. In some cases, multiple API design styles may be offered for a single digital capability.

There are a few ways that business and product requirements may be captured and used to drive the design of digital capabilities as APIs. The ADDR Process recommends using job stories, which are rooted in the jobs to be done approach to design.

Focusing on the Jobs to be Done

Jobs to be done (JTBD) are the identified needs fulfilled by a product or service offering. This includes capturing how a customer problem, the task to be performed, and the desired outcome that should result.

JTBD was formulated by Clayton Christensen, author of “The Innovator’s Dilemma”, as a method of taking the viewpoint of the customer when designing a product or service. JTBD ensures that the product addresses a specific need and therefore has a better chance of gaining market adoption. It starts by identifying the needs of customers, the job, and then defining how a product or service will fill that need.

In JTBD, jobs are more than just functions that need to be performed. Jobs are really about the desired outcome or accomplishment. Jobs may be new and unsolved or may be solved in some way that doesn’t quite meet the customers’ needs. Building a product that produces the desired outcome is one that considers all of these factors about the jobs to be done. JTBD applies to APIs as well as all other aspects of product and software design with the organization.

The idea behind JTBD is rooted in the Voice of the Customer (the VOC) from the mid-80s, where product managers attempted to improve product performance by getting into the mindset of the customer. VOC combines market research data with specific wants and needs that have been identified through surveys and customer interviews.

Christensen also reminded us that there is an emotional and social side to the jobs that a product attempts to solve. The job extends beyond the immediate problem to include a reduction or removal of the anxiety involved. They must provide positive experiences while producing progress toward the desired outcome. Some may even go so far as to offer enjoyment while completing the job.

Principle #2: API design starts with an outcome-based focus

A focus on the outcome ensures the API delivers value to everyone. This requires a product-thinking approach to API design, rather than purely one that is driven by data and systems integration. The ADDR process is focused on identifying and realizing these outcomes.

What are Job Stories?

Customers and users don’t care about APIs, microservices, serverless, or the flavor of front-end framework used. They want a solution to a problem. They care about outcomes.

Job stories capture the jobs to be done for any product, including the customer motivations, events and expectations for a new product, service, or API. They frame every design problem from the perspective of the customer. Job stories seek to identify the problems that customers have and the eventual outcome they wish to achieve. Jobs are identified that will solve these problems. APIs will offer digital capabilities that will power these jobs to be done to produce the desired outcome.

Job stories were created by Alan Klement and are based on JTBD formulated by Clayton Christensen. They offer a simple framework to capture all of the aspects of the job to be done.

Teams producing job stories will find that their API designs focus more on the desired outcomes of the audience. They will also have the details necessary to create acceptance criteria for automated tests. It is important to note that job stories shouldn’t contain implementation specifics. Instead, they should elaborate on what needs to happen to make the necessary progress to deliver the outcome.

The ADDR Process leans heavily on job stories to capture business requirements in a customer-centric way. Job stories express customer requirements in a simple format and provide a natural way to identify digital capabilities that will drive API design.

The Components of a Job Story

Job stories are composed of three components using the “When, I want to, so I can” format:

■ “When”: The triggering event to establish causality – the situation or reason why the customer desires the outcome. Triggering events are key indicators for when an API will be used.

■ “I want to”: The capability is what the customer has identified as the action that needs to be taken. The capability identifies the important role that the API will play to deliver the desired outcome. It will also be used to deconstruct the operations that the API will deliver.

■ “So I can”: The outcome is the desired end state. It is the result of applying the capability when the triggering event occurs. The outcome drives the acceptance criteria for the API design.

Figure 3.2 shows an example Forgot Password job story, highlighting its three components:

The example job story in Figure 3.2 demonstrates how a job story may be used to inform the design of a digital capability. In this case, it captures a digital capability titled “Reset my password.” This would be one of many digital capabilities the API will need to offer to meet the needs of the target customers.

Writing Job Stories for APIs

The details used to create job stories may exist in different forms. Some details may identify a problem that needs to be solved. Other details may indicate the desired outcome but lack other information.

Since there is no right or wrong way to approach creating job stories, three methods are provided here to help teams navigate the many situations that are encountered in the real world. Apply one, two, or all three methods to compose job stories that capture customer needs. Then formulate the insights into the job story format of “When, I want to, so I can.”

Method #1: When the problem is known

This method is the most common as customers are usually good at identifying the problems that they need resolved. In this case, use some or all of the following questions to explore the problem space and identify the remaining two components necessary to compose the job stories:

■ What is the desired outcome that they wish to experience to solve the problem?

■ What is the job required to achieve the outcome?

■ Given these two answers, does the original problem best describe the triggering situation, or is there a better way to express the problem in job story format?

Method #2: When the desired outcome is known

There are times when the desired outcome is understood, but the triggering situation is not. This may be the case when customers have a desired outcome in mind but may not be sure why they need it. Use the following questions to guide the discussion and help to formulate job stories based on their desired outcomes:

■ What is the problem, as described by the customer or stakeholder, that drives the desired outcome?

■ What is the job required to achieve the outcome? If multiple tasks are identified, summarize them into a single job description.

■ Does the desired outcome still best express their need, or should it be re-written?

Method #3: When the digital capability has been identified

There may be times when a customer has identified the digital capability that they desire. This is common when customers are subject matter experts or have spent considerable time thinking about the problem. In this case, ask the following questions to help validate the digital capability that they identified and fill in the missing pieces of the job stories:

■ What is the desired outcome that they wish to experience?

■ What is the problem or triggering situation that demands the outcome, as described by the customer or stakeholder?

■ Does the identified digital capability help to produce the desired outcome? If not, is there a better way to word the digital capability or one better suited to solve the problem?

Overcoming Job Story Challenges

When teams begin to construct job stories, they may encounter three issues: the job stories become too detailed, they become feature centric, or they may need additional user context. All of these issues may be resolved using the suggestions below.

Challenge #1: Job Stories Are Too Detailed

Job stories should contain enough context to enable future deconstruction of the job story into independent tasks (more on this in the next chapter). However, job stories may become littered with all kinds of details that will be important in the near future. This is a common occurrence when job story authors are concerned about losing track of specific details that have been previously discussed. Consider the following example that has too many details:

When I find a product I want to buy,

I want to provide the quantity, color, and style of the product

So I can add it to my shopping cart and see the current subtotal, shipping costs, and estimated sales tax.

When a job story contains too many details, extract the details as additional items below the job story. This will ensure the details are not lost, while keeping the job story clear and focused. Here is the same job story, rewritten with the details moved outside of the job story narrative:

When I find a product I want to buy,

I want to add the product to my shopping cart

So I can include it in my order.

Additional details:

■ The following fields will be required when adding an item to a cart: quantity, color, and style

■ The shopping cart will then show the current subtotal, shipping costs, and estimated sales tax.

These details can be extracted into bullet points in a document or Markdown file or added as an additional notes column in a spreadsheet.

Challenge #2: Job Stories Are Feature Centric

Those familiar with writing user stories tend to craft job stories with a focus on features rather than outcomes. This may be encountered for existing products that already have a user interface or high-fidelity wireframes. Instead of focusing on the problem and desired outcome, the author of the job story immediately jumps to the solution.

The following is an example of a job story that focuses on feature details:

When I find a product I want to buy,

I want to add the product to my shopping cart by clicking a yellow button

So I can include it in my order.

Consider adjusting job stories that contain features into a standard job story structure. If the team is concerned about losing details about the feature in the job story, move feature details into an “additional details” section of the job story. This will allow the feature details to be referenced at a later point in the design process.

For example:

When I find a product I want to buy,

I want to add the product to my shopping cart

So I can include it in my order.

Additional details:

■ The button to add a product to a cart should be yellow

■ The label should say “Add to Cart”

Challenge #3: Additional User Context is Needed

User stories have the benefit of the “As a” phrase used to start the story. This phrase helps to identify the persona that the user story is designed to address. However, some products may end up with a long list of user stories that start with the same prefix, e.g., “As a user,…”. If this is the case, then the persona isn’t a necessary detail after all and just clutters the user story.

The job story format by default doesn’t concern itself with the persona. However, there are times when the details about a persona help to shed additional context in a job story. In this case, substitute the persona name in the “I want to” clause, as demonstrated in this example:

When a decision is needed on the dates for a special sale,

A manager wants to produce a sales report with customized criteria

So the manager can view the sales history and determine the best days to run the sale.

This approach provides a nice blend between job stories and user stories.

Techniques for Capturing Job Stories

Since there are no specific tools for capturing job stories, teams have the flexibility to select a tool that works best for them. Below are a few recommendations, but feel free to use anything that enables communication and collaboration within and across teams.

■ Spreadsheets – Spreadsheets are the universal tool and are quite useful for capturing job stories. One job story per row in a spreadsheet will suffice. The first column should be a job story identifier. Dedicate the next columns to each of the three components, “When, I want to, so I can.” Finally, add a fifth column for notes. Since many spreadsheets support collaborative editing, multiple people can review, comment, and contribute as needed.

■ Documents – Documents are also useful, though they are a bit less structured. They are useful when teams wish to mimic an index card style for capturing job stories. Start with a heading that indicates the job story identifier, such as a number or brief description. Place each of the three components of a job story, “When, I want to, so I can”, on a separate line for readability. Leave room for capturing additional insights or details as a list of bulleted items. Add a blank space between each job story to help separate each one or assign one job story per page.

■ Markdown files – Markdown is a text file with an approachable syntax useful for capturing job stories. Markdown files may be used to export job stories into HTML, PDF, and other formats. Use a single Markdown file with all job stories or create a Markdown file for each job story. Combine with a version control system, such as git, to view a history of changes to the job stories. Of course, this approach is targeted at teams with deeper technical expertise.

A Real-World API Design Project

To explore the API design process, a fictitious bookstore called JSON’s Bookstore will be used. The bookstore is a SaaS-based online book company that ships books from its warehouse to customers all over the world. This fictitious business derives from many consulting engagements over the years. It will open the opportunity to better explore and apply the various concepts of API design with a real-world context. Teams will see the various challenges involved with designing APIs that are meant to support different audiences and support operations, commerce, and partner integration. It will also help teams explore the challenges involved with applying design techniques to existing APIs that already exist.

JSON’s Bookstore must design a series of APIs that will support online commerce, order fulfillment, inventory management, and catalog management. The company will also need to support integration with partners and customers. Along the way, the API surface area will increase, requiring JSON’s Bookstore to find ways to manage and govern the APIs in a scalable way that doesn’t slow down its development velocity.

Job Story Examples

The job stories in Table 3.1 were identified to support the shopping and purchase experience for JSON’s Bookstore. As an exercise, review the job stories and try writing some additional ones to practice the job story format.

Refer to the full list of job stories using the API workshop examples available on GitHub.

Summary

APIs are digital capabilities that help turn desired outcomes into reality through automation. An API designed with these outcomes will help to deliver a better API design for the target audience.

Job stories offer contextual understanding of the desired outcomes and the digital capabilities that will be necessary to make them a reality. Through the process of composing job stories, a shared understanding of business and customer needs for all stakeholders is established. The more effort that is placed into composing job stories, the more likely the API will meet the needs of customers. Job stories are the first artifact needed to align all stakeholders prior to API design. The next chapter will discuss how to expand job stories into the activities and activity steps that will be the foundation for API design.