A playbook for API-first transformation at scale- The Business Capability Model

In the previous post, we’ve discussed the API platform team structure and various roles & responsibilities. In this post, we’ll discuss the core building block of the API platform- the business capability model.

When we think about APIs, we’re thinking them as the logical definitions of business capabilities and micro-services as the physical artifacts that implement these logical definitions (APIs) and service requests. A business capability helps you to define the service boundary, or the purpose of an API and a business capability model is the collection of all the business capabilities from one or more business domains. Defining the service boundaries is one of the hardest things to do and not an exact science. It requires deep thinking of your business domain, goals/requirements, careful thought and deliberation, and collaboration with multiple stakeholders (domain experts, software architects, business owners). If well executed, a business capability model promises to provide a solid foundation for building customer focused API products and services. When it goes wrong, it leads to purposeless APIs, incorrect service boundaries, poorly designed interfaces, chatty interactions, you name it.

So, how does one build a business capability model?

Using Domain-Driven Design to build the Business Capability Model

A framework that you could use to build a business capability model is, domain-driven design. Domain-driven design or DDD (the term originally conceived by Eric Evans) is an approach to software development that centers around a set of principles and design patterns you could use to define the shared language for a business domain. Domain-driven design is usually practiced in two phases- strategic DDD and tactical DDD. In strategic DDD, you perform domain analysis to come up with the domain’s vision statement (overview of the domain that clearly describes its value proposition) and decompose the larger business domain into a network of bounded contexts (sub-domains or problem spaces) that together make up the business domain. In the tactical DDD phase you expand the bounded contexts to create the domain model that consists of entities, value objects, aggregates, and domain services-together they make up the ubiquitous language for the domain. You then go on to repeat this excercise for each business domain, which then leads to a well-defined business capability model and business domain(s) vocabulary.

Identifying the business capabilities

There are many ways you can approach to identify the business capabilities to build a business capability model. One way to approach it is to decompose various business processes to identify the business domains and business capabilities, The other way to approach this is by studying your various service assets and the codebase. Neither of the approach is right or wrong, but in practice, the former leads to better results than the latter. In the latter, it is easy to get trapped in the organizational boundaries, biases, implementation details and then leak them into the model. Regardless of the approach you take, it is important that you validate the model with all the users/consumers of the model and keep iterating on it from the feedback received, until the model reaches its desired state. The model should also make sense to anyone outside the domain and to audience at all levels (developers, architects, product managers, business leaders), if not, you should go back to the drawing board and rework on it. Remember, you would use the model to discuss everything relating to your domain (be it solutions, or budgeting or customer adoption) so contnuous validation of the model is very important. Lastly, when working on the capability model, it is always a good idea to validate it with any of the industry references, if it is available. For example, if you are in the banking and finance domain, then the BIAN model is a good reference to validate.

To demonstrate how a business capability model would look like, let’s take , identity as the business domain, and the strategic DDD modeling excercise led to the following coarse-grained business capabilities (bounded contexts in DDD)

• Auth: A capability that for handling all of authentication and authorization functionality.
• Accounts: A capability to manage a user’s account lifecycle.
• Onboarding- A capability to manage the on-boarding of users.
• Offboarding-A capability to manage the off-boarding of users.
• Devices- A capability to manage device identities.

In the tactical DDD phase, you go on to expand each of these business capabilities to describe all entities (e.g. Account, Device, Session, Notification), aggregates (e.g., Account, Device), Value Objects (Address, Email, Phone etc.), to create the ubiquitous language for the identity domain. Now that you have all the problem spaces for the identity domain and the domain vocabulary, you would then use the domain model to describe all entities in the identity APIs and in the service implementation on as-is basis. If you can sense something important here, the domain model has no technology or API protocol affinity, which means, it is durable, and you can use it to build APIs using any API protocol, now or in future.

Given below is a diagram that describes a sample business capability model, consisting of three business domains- identity, payments and merchant.

Note- In the above diagram each business domain has several business capabilities, and each capability may be described by an API contract and implemented by a micro-service. Also note that there’s not always 1:1 mapping between a business capability, an API, and a service. For example, in case of Merchant-Checkout capability(a coarse-grained capability or a capability group, the APIs and services are defined at the level of a fine grained capability orders (which is a DDD aggregate or a transactional boundary) and checkout sessions (another aggregate).

Maintenance and evolution of Business capability Model

Building of a business capability model is not a fixed one-time exercise. It should keep evolving with new business requirements and usage. You build a baseline version and if you have done it right, you would only keep adding new capabilities to the baseline version or may be in some cases, further decompose an existing business capability to more finer capabilities. For example, in the identity domain, if you want to now support federated identities, you can add a new capability, “Federation”, to manage the lifecycle of federated identities. Remember, like the baseline model, whenever you add a new capability, you always make a point to validate it with your consumers. And as always, we apply product thinking for everything and the best way to do this is by treating the business capability model and the domain vocabulary as a product and manage it like any other product (Full lifecycle management including versioning and deprecation). The roles “Portfolio Manager” together with “API Product owner” and “API Platform Architect”, described in the previous post are responsible for managing the business capability model.

Integration of the Business Capability Model with the Product Development Lifecycle (PDLC) and other tools

Now the actual catch- You have defined the business capability model so what’s next?

You might have come across so many instances, in many companies, where a domain modeling exercise is performed as part of some initiative to begin with that is mostly academical in nature and done by a group of enterprise architects, documented, and then ignored by everyone. It only remains on paper, many stakeholders including the developers wouldn’t even know that it exists or even if they know, it exists, they don’t know how to make use of it. It is thus important to integrate the business capability model with the product development lifecycle and with all other tools/processes, only then you realize its full potential. You would then have a purpose, business value driven, strong customer focus for everything you build, be it delivering your end-user facing products, or determining which area to invest, which area not to invest, your operating cost, your team performance, and the list goes on. As an example, with the identity business domain we conceptualized in the previous section, you can, for example, utilize the model for the following things,

• You can create a business unit to focus solely on the identity domain.
• You can measure the call volume on per business capability basis (instead of per service basis-service names are mostly weird and none except the service team would understand its meaning). For example, you can say “The capability Identity-Accounts serves 10M active users”.
• You can describe your observability data around each capability. For example, you can say, “The capability Identity-Accounts had 100M API calls”, “The capability Identity-Accounts had 500 failed client interactions on a business day”.
• You can create autonomous micro-services teams on per business capability basis, measure the productivity in terms of features delivered and lines of code), and measure the quality.
• When complete, the business capability model also provides visibility into the capability gaps in comparison with your competition. Business leaders can then use this data to decide and bridge the gap either organically or inorganically.
• You can also produce various other insights at capability level such as customer support calls received to determine its effectiveness.

With a business capability model covering all of the business domains in the company, you can even create a portfolio dashboard for any business executives(without requiring to do any taxonomy translation to present to different types of audience), to monitor or get all the data they are interested in.

Note: In the next post, we’ll understand how the business capability is leveraged to perform API discovery and, in the API PDLC, (to detect API capability overlaps in the proposal process and find the API’s position in the capability model-The API portfolio alignment phase).

Final thoughts-Is Business Capability Model only for large organizations?

This is a typical question that often comes up, “We’re a small company with very few services, do we need to follow DDD or build the business capability model?” The answer is YES. Regardless of the size of your company or the number of teams you have, defining a business capability model helps you build purpose driven and customer-focus API products. It helps define clean service boundaries and provides a solid footing (you don’t need to start a large API-first transformation project later). The trick is to not just define one, but also integrate it with the product development lifecycle to realize the full potential, it will for sure pay you back.

This article is the third of seven that explores the API-first transformation playbook in detail. In the next post, we’ll discuss how define a customer centric API product development lifecycle to manage the lifecycle of your API products.