5. Identifying API Boundaries
Total unification of the domain model for a large system will not be feasible or cost-effective.
Eric Evans, Domain-Driven Design
Every API provides a mental model for how developers will integrate with it to produce the desired outcomes. Establishing the scope and responsibilities of an API also helps guide the design of this mental model, contributing to a more positive developer experience. By borrowing techniques from DDD used in identifying bounded contexts, candidate APIs are identified and the responsibility of each API is clearly defined from the artifacts produced in the Align Phase (see Figure 5.1).
Figure 5.1 The first step in the Define Phase is to identify API boundaries
Output from activity step identification, as detailed in Chapter 4, is useful in finding boundaries and therefore candidate APIs. These candidate APIs realize the digital capabilities that will produce the desired outcomes captured in job stories, as detailed in Chapter 3. Before getting started with the process, it is important to understand how some mistakes in defining API boundaries can lead to a poor developer experience.
Avoiding API Boundary Anti-Patterns
It is important to clarify the intent and scope of an API. Identifying the scope of an API helps developers find the right one for the job. Without a clear scope and set of associated responsibilities, APIs will suffer from common API boundary anti-patterns.
The Mega All-in-One API Anti-Pattern
Even the most experienced API designers are faced with challenges when trying to determine how many separate API products they need.
Creating a single, large API product makes it difficult for developers to find what they need quickly. Likewise, many small API products, perhaps as a result of externalizing microservices individually, may result in fragmentation and frustration. Applying clear API boundaries helps to reduce confusion around very large or many small APIs.
The Overloaded API Anti-Pattern
Organizations with multiple products or that offer a platform comprised of multiple APIs have additional challenges ahead. All too often, organizations want to design the perfect “Accounts API” or “Customer API” that will be the single place to find out all the details about an account or customer. What starts as a well-intentioned goal eventually leads to a single API that tries to do everything but ultimately does nothing well.
In the bookstore example, the term “books” could imply one of several contexts:
■ Books that are entries in the catalog of available products to purchase
■ Books available as part of the warehouse inventory
■ Books added to a shopping cart
■ Books that are part of a placed order
■ Books that have been shipped as part of an order
Creating a single Books API is likely not the best route to clarity or sanity. API changes would be constant as new contexts around the term “books” are introduced. The result are operations that mix and match the term in different ways until the API becomes a confusing mess. Not only does this lead to a poor developer experience, it also contributes to significant delays when delivering new enhancements in the future.
In larger organizations, a single team may become responsible for most of the API through this incorrect assumption that a single Books API is the best way to organize support across the book catalog, inventory, shopping, and fulfillment processes of the organization. The velocity of delivery is greatly reduced as the remainder of the organization waits for the single team to add the operations needed to support new functionality.
Instead, seek to clarify single word terms such as “book” with more context. For example, a Books Catalog API helps to limit the scope of API operations to those involved to catalog management. Within this clearly defined scope are additional responsibilities including managing public descriptions, associated author metadata to each book, book covers, sample chapters, and more. Only those interested in catalog management need to work with this API.
The Helper API Anti-Pattern
Nearly every development team has at one time built a helper library. This library has a mixture of little utilities that are scattered all around the codebase. The namespace used to store the helpers, e.g. com.mycompany.util, is referenced all over the codebase.
Some APIs suffer the same challenges as the sad, overused helper API. These are APIs that have a mixture of uses but aren’t cohesive as a unit. Developers integrating with the API struggle to understand when and where to apply each one. The lack of scope and responsibility of the API makes the developer confused and unable to use it effectively.
Bounded Contexts, Subdomains, and APIs
The goal of an API boundary is to unify on the ubiquitous language while reducing overall coordination between teams as much as possible. In the case of web APIs, boundaries may offer one or more network interfaces to support all the operations within the bounded area. Each boundary should be owned by a single team that is empowered to build and own everything within the boundary.
Defining clear boundaries is an important factor for APIs as it helps to accelerate the API design and development process by scoping APIs to a specific set of responsibilities. The terminology used for API operations and resources should reflect the bounded context’s ubiquitous language as well. For larger or more complex boundaries, further decomposition may be required, perhaps resulting in additional APIs and/or services hidden behind the API. Over time, boundaries may shift as more is learned about the solution.
The challenge most teams face is how to identify bounded contexts for their APIs. Team members may just “know it when they see it”, while others may place boundaries around a specific portion of a domain model. Neither of these methods result in a repeatable, teachable process that clearly identifies the scope of an API. Instead, it is recommended to use the EventStorming canvas and activity steps artifacts from the Align Phase to help identify boundaries.
A Note About API Boundaries and DDD
While this chapter seeks to incorporate common DDD terminology and practices for identifying API boundaries, it is also meant to support organizations that have not adopted common DDD practices.
This chapter seeks to find a middle ground that supports practitioners familiar with the intricacies of DDD, as well as those less familiar. In either case, there are many useful lessons within DDD that still apply to organizations not fully engaged in DDD practices. Organizations more familiar with DDD may wish to introduce additional practices that go beyond the scope of this chapter.
As teams complete their API design, refer to Vaughn Vernon’s excellent book, “Implementing Domain-Driven Design”, for further details on implementing DDD.
Finding API Boundaries Using EventStorming
As mentioned in Chapter 4, EventStorming helps to unify terminology while aligning teams with an understanding of processes, business policies, and system interactions. By examining the language used throughout the EventStorming canvas, hints about possible API boundaries begin to emerge as terms and focus shifts. This is demonstrated by language pattern shifts as indicated in Figure 5.3.
Figure 5.3 An EventStorming canvas is helpful in finding shifts in language, leading to the identification of bounded contexts.
By noticing the shifts in terminology, boundaries start to emerge. Identify and name each of the boundaries. Then, assign a web-based API for each boundary as a starting point. The API will offer the API operations necessary to deliver the digital capabilities for that boundary.
Teams may also choose to use the aggregates identified in EventStorming as hints to API scope. While this offers some additional insights into API boundaries, it may not always be the case. If aggregates were captured based on fine-grained responsibilities and focused on a single responsibility, they are more useful for identifying internal modules or services behind the API. However, if aggregates were grouped at a more coarse-grained level, they may succeed in identifying an API that is responsible for orchestrating outcomes.
For some EventStorming sessions exploring a limited scope, there may only be a single boundary. For most solutions, however, there will be at least two boundaries identified on an EventStorming canvas.
Figure 5.4 highlights three specific boundaries that qualify as separate APIs, based on the insights provided from EventStorming.
Figure 5.4 APIs identified through the shift in language on the EventStorming canvas.
Finding API Boundaries Through Activities
While EventStorming helps to find boundaries by design, it isn’t the only method for guiding the identification process. The same approach may be used by reviewing the activities and activity steps produced by subject matter experts already familiar with the necessary processes and workflows, as described in Chapter 4. This is a particularly effective approach when considerable effort has already been invested in capturing requirements.
Look for shifts in language like what was described previously using EventStorming. Often the activity step names and/or descriptions have a basic sentence structure with nouns and verbs. Make note of where the nouns shift in the activity steps. The nouns acted upon may offer clues to where boundaries exist. When steps shift to a new set of nouns, mark the location and use this as the starting point of a new boundary. While not as comprehensive as EventStorming, the activities and activity steps will offer insights into shifts in language that demonstrate a shift in a boundary.
As an example, the activities and activity steps from Table 4.2 in the previous chapter are presented below. Notice the shift from Books to Cart, then to Order and Payment. These shifts provide a starting point for identifying boundaries, from which APIs are formed.
Table 5.1 Example activity steps for JSON’s Bookstore, with separators to indicate the shift in vocabulary that indicates boundaries.
Naming and Scoping APIs
Next, the boundary is given a name to present the API that will be designed. Seek to assign a name that includes the scope, outcome, or target audience. Examples of well-known API names include Twitter’s Followers API or eBay’s Seller API. Avoid the use of the terms ‘service’ or ‘manager’ as they are generally not useful in understanding the purpose of the API.
The APIs in Figure 5.4 are named Shopping API, Order Creation API, and Payment Processing API. This is a good start and clearly articulates the scope and responsibility of each API.
Note
Some API designers may prefer to combine the Order Creation and Payment Processing APIs as they could be considered cohesive and therefore should exist as a single API. They have been separated in this simple example for instructional purposes. However, field insights dictate separating order creation and payment through clearly defined boundaries allows for more complex payment processing at a future time, without burdening the order creation boundary with the added complexity.
Finally, separate the activity steps into the corresponding API based on the boundary it represents. Table 5.2 captures the Shopping API, including the activity steps relevant to the API.
Table 5.2 The Shopping API, discovered through boundary identification, with corresponding activity steps from JSON’s Bookstore example.
Table 5.3 captures the checkout process for the Place an Order digital capability.
Table 5.3 The Order Creation API, discovered through boundary identification, with corresponding activity steps from JSON’s Bookstore example.
Finally, Table 5.4 captures the payment step as part of the Place an Order digital capability.
Table 5.4 The Payment Processing API, discovered through boundary identification, with corresponding activity steps from JSON’s Bookstore example.
With the boundaries clearly defined, API modeling can begin. This will lead to API profiles that define the operations and events each API will offer. This will be detailed in the next chapter.
Summary
APIs benefit from careful scoping and assignment of responsibilities. Applying boundaries helps to identify one or more APIs that will be required to deliver the desired outcomes captured as job stories. This prepares the way for the next step, API modeling, where a blueprint of the API will be formed, and the foundation laid for API design.