Revisiting API Design

API design is a well-established topic. However, I wanted to revisit this topic using Domain-Driven Design principles. API design starts by identifying the digital capabilities we intend to deliver to our customers, internal or external. We need to spend some time articulating these capabilities. DDD can help us in this regard with a structured and well-defined process.

In the beginning, the scope can be system-wide, high-level. We start by identifying bounded contexts in our business domain. Bringing domain experts from product, engineering, customer service, etc., is a great idea. Tools such as Event Storming or Domain Storytelling are well suited for such collaboration among domain experts. Once we identify high-level bounded contexts, we can look deeper into a particular sub-domain. Note that this is an iterative process. We validate and gather feedback from the stakeholders. We can make as much discovery as needed in each iteration.

Some folks may dismiss spending time up front in such a discovery. From experience, these discussions pay dividends many times over. The following quote resonates in this regard:

Big design up front is dumb, but doing no design up front is even dumber.

-- Dave Thomas

DDD encourages us?not?to think along technical boundaries but instead along business domain boundaries. This shift in focus makes a huge difference in our approach to delivering digital capabilities to our customers.

Figure 1?above depicts an example where we discovered three bounded contexts in our domain. Within each bounded context, we also identified some aggregates. As a reminder, aggregates in DDD are cohesive clusters of domain objects that are treated as a single unit for consistency and transactional boundaries.

We achieve the following results from this exercise:

1) We are getting a good sense of the modularity in our design. Modularity is the hallmark of a good software design, as pointed out by Parnas.

Modularity is the single attribute of software that allows a program to be intellectually manageable.

-- David Parnas.

2) Our APIs need to be aligned with the aggregates. These are the aggregates that participate in the digital capability that we need to expose.

3) Aggregates define our domain model.

4) We use the bounded context's ubiquitous language to enrich our domain model. Naming in software is hard, so this is a big help.

5) Our bounded contexts define a highly cohesive boundary for the aggregates.

6) Bounded contexts are loosely coupled with each other. Hence the corresponding aggregates are loosely coupled.???

As a side note, we should strive for information hiding in our API design. We do not want our abstractions leaking across the API boundary. The information includes data and semantics. APIs are immutable contracts. Hiding our internal details allows us to make changes without worrying about breaking the API contract. As nicely put by Parnas:

Information hiding is the fundamental principle of modular design. It allows us to encapsulate implementation details, promoting abstraction and reducing dependencies.

-- David Parnas

Our API design is off to a great start by following DDD principles, but the journey has just begun. Taking our domain model to production requires many additional steps. For example, we need to decide whether REST, gRPC, GraphQL, or any other emerging technology is suited for our use case. Using the domain model, we still need to define the full API specification that captures inputs and outputs detail. We must think about documentation, testing, monitoring, deployment, security, etc. Since that is beyond the scope of this article, I would refer you to an excellent book by James Higginbotham [1]. There is also another good reference on API patterns [2]. These books are part of an auspicious Vaughn Vernon Signature series I am a big fan of.

Summary

By following the DDD approach in our API design, we can adhere to software design principles of modularity, encapsulation, loose coupling, and high cohesion.

Our customers will appreciate the care we took in designing the APIs. It will help them get a better mental model of the APIs.?

References

[1] Principles of Web API Design by James Higginbotham.

[2] Patterns for API Design by Olaf Zimmermann et al.