The analysts' guide to APIs

Almost every business or technical analyst today understand the benefits of exposing business capabilities through APIs. But how can you best achieve this?

It’s easy to get pulled into a technology-first view of APIs. After all, an API is an application programming interface — it just sounds very technical. As a business analyst, this might be confusing — even intimidating — especially when faced with the myriad of non-functional requirements (NFRs) documented in REST style guides, error codes, versioning, and use of HTTP headers.

Before you find yourself hurtling down that particular rabbit hole, take a breath and ask yourself a simple question: Where is the user in all of this?

In this article, we’ll explore the benefits of considering user stories when building APIs.

Putting the user front and center

Whenever we think of building APIs, we recommend coming back to the reason we need applications to talk to each other in the first place. An API is usually created because of the needs of the business and users. Generally, these APIs fall into two categories:

• Private APIs. These enable businesses to ‘wrap’ or integrate with aging technology that they may eventually replace; to future-proof new front-end development or new capabilities that depend on existing technology.
• Public APIs. These enable businesses to expose their capabilities to other businesses or consumers. For example, an API that allows external re-sellers to search for products or place orders for products through a programmatic interface. One example in this category is Best Buy.

We can look at the user stories through a different lens for these two categories. But both provide useful mechanisms that help companies on the path to adopting an ‘API as a product’ approach.

Private API stories

When it comes to private API initiatives, it can be tempting to simply focus on ‘just wrapping the existing system’. Beware: this can lead to a technology-first view of the API stories, one based on the technical design of the existing system. When the existing system is a monolith or has limitations — which is likely to be the reason the organization is pursuing a wrapper — you need to be sure that the stories reflect the desired business capabilities and not the existing technology.

Let’s take an example:

• Start with a narrative to express the need
  Do you see stories in the backlog that take this approach? For instance: ‘As a developer, I need an API to fetch a list of products’. Here’s how we could re-write this: ‘As a developer, I need the products available for purchase so that I can show them to our customers via our website or mobile app.
  
  The tasks for this story, or breakdown of the feature, would need to address: security; the number of data fields needed just to display the order screen (as opposed to having an API that returns all the possible fields associated with a product); and some core API functional approaches for things like paging and sorting.
   
• It’s not about just ‘slinging data’.
  Sometimes the ‘fetch the list of products’ story focuses too much on all the data that is associated with a product. That could involve hundreds of data elements, and filtering the information based on the customer’s status. You can simplify things by embracing the principles of YAGNI, and remembering that APIs will evolve over time. Where possible, you should avoid pursuing an exhaustive interface to represent the entire structure and capability of the existing system. Keep the Tolerant Reader Pattern (TRP) in mind, since consumers of a REST API can and should adopt TRP, and REST APIs can be expanded in non-breaking ways as consuming application needs evolve.
  
  If the API is intended to expose business capability from an existing system, ensure that the only the information that is needed to support the business case is exposed.
  You can apply the Tolerant Reader Pattern to API design; if the existing system manages 200 data elements and 20 behaviors or events for a core business entity such as ‘Product’, then: “Design the client or service [or API] to extract only what is needed, ignore unknown content, and expect variant data structures.”
  
  YAGNI and Tolerant Reader concepts can direct the API stories to real-world usage, not the underlying physical schema or all available data managed in existing systems.  

Interlude: memories of COM

Back in the day, COM programmers (“Each interface is an immutable contract of a functional group of methods”) had to agonize over interface design. COM interfaces were a way to create an API, just like REST. But, REST frees us from immutability — and we can move more quickly to create APIs that align with user stories, are tied to business capabilities, and are less concerned with existing data structures or schema. In some sense, for private API stories, the ‘Backend For Frontend’ (BFF) might be considered the ‘real’ API, with the fulfillment of the BFF via facades and adapters viewed as the concern of engineering. It’s worth considering that a business Analyst’s efforts could focus more on BFF when dealing with private API stories, and have facades/adapters and BFF fulfillment falls into the category of NFRs, or potentially ‘API as a Product’ concerns.

Public API stories

When your organization decides to expose a public API to enable communication with consumers or other businesses, you have to understand the underlying business needs and motivations.

Successful public APIs have clearly defined themes and are often branded. For example, the Best Buy API has clear messaging, defining the purpose of each API domain, and is written in such a way that a non-programmer can understand why Best Buy publishes these APIs. Amazon has a wide array of digital offerings, with APIs grouped by major service domain, and again, the intent is clear and understandable from a business perspective.   

Outside of the e-commerce world, we can see good examples of business-focused public APIs and branding from Lyft and Sabre; the completely API-driven business empire created by Twilio; and an evolving vision of APIs from Mercedes Benz. It’s instructive to look at the shapes and the core features of these APIs because they reflect the core business capabilities and visions of their companies.
 

What’s in your analysis tool box?

Domain Modeling and Event Storming are great tools for analysis, and for driving out API stories from a business and usage perspective. To avoid gumming up delivery efforts, we think it’s useful to define a reasonable scope for these exercises, and avoid complex ‘enterprise-wide’ modeling efforts.  

Event Storming is particularly useful if you get the sense that all the business capabilities are being forced into a REST API. REST in itself is not a complete solution: it’s just one tool that enables programmatic communication. REST lends itself very well to request-response needs (‘get products’, ‘post an order’). But with Event Storming, you can drive out needs for extending that communication to events and messages. For example, when an order is placed, who needs to be notified?  Business-truthful APIs consist of not only information and behaviors (often exposed via REST), but also events.  

The business-truthful concept goes back to the basics of object-oriented programming, as most business objects consist of properties and methods (which align nicely with REST), and events. Business-oriented analysis can provide the wake-up call when an API effort is getting conflated with ‘just build a REST interface around our existing systems’.

Using epics to track business value

One of the most commonly recommended approaches for breaking down work is through using service endpoints as story boundaries. However, with such an approach, you may run the risk of missing the user again — especially if the stories are endpoint-specific and not necessarily aligned with business value.  

A true business flow may require calling a series of several endpoints — say, customer creation, product selection, checkout, billing. Epics are a good way to track these business flows across several stories, which may be captured under different features or even different teams on larger programmes of work.

Once you’re tracking business flows with epics, they need to become your primary measure of velocity, as stories alone could give a false sense of progress. A common symptom of this is when your team’s burnup shows you’re delivering well but nothing seems to be ready to showcase to business stakeholders.

When you change your burnups to track completed epics, the result will help you appreciate the scope of the problem. Likely you’ll find that you have a lot of epics in progress and not getting to completion soon. Collaboration with your product owner to identify key business flows under epics and prioritize and limit the number of epics in progress.

The API is a product

At ThoughtWorks, we’re fans of the ‘API as a product’ technique — to the extent that it was moved in the ‘trial’ ring in our Technology Radar Vol. 16. private and public API efforts can be viewed through a product lens that extends the business motivations for the API. Using a product lens, we view the true customers of the API as software developers. That means developer experience, ‘time to hello world’ and technical consistency of structure and payload can be included as elements of experience design, in addition to developer needs for API discovery and documentation that enable effective use of the API.

There are ‘user stories’ to be written when viewing APIs through this lens, but the ‘API as a product’ technique does not exist independently of the original business need and motives for an API. As champions of these needs and motives, business analysts are responsible for keeping the team’s efforts focused on business capability and enabling ultimate user consumption of the APIs. This allows an adventurous and motivated business analyst to extend their skills to product management and more technical non-functional requirements management. All are necessary ingredients for a successful API strategy.

Pulling it all together: API strategy

Successful delivery of an API project relies on a combination of business-driven user stories, the appropriate API and Service Management Architecture, and an ‘API as a product’ considerations.

An API strategy is much more than ‘hide the complexity of my old systems behind a REST interface’. An API strategy ensures that:

• High-value business capabilities are exposed digitally
• APIs provide a delightful developer experience
• APIs are true to the business versus existing technology or organizational structure (be sure to navigate the perils of Conway’s Law)

Crafting an effective API Strategy is outside the scope of this article, but effective user stories are a critical piece of the puzzle. Like all software, an API project is only meaningful if it is driven by true business needs, with the goal of delighting users.

In future posts, we’ll share more insights on API strategies, and adopting an ‘API as a product’ approach to exposing your business capabilities on a digital platform.