Modeling Coherent and Composable Business Resource APIs

or: Where Do Business Resource APIs Come From?

TRGoodwill

Published in

API Central

8 min readAug 22, 2022

Domain Driven Design

Stable, domain aligned business resource APIs are arrived at via a process of Domain Driven Design. Domain driven design “divides up a large system into Bounded Contexts, each of which can have a unified model” Fowler, M 2014, Bounded Context. DDD helps us control complexity by breaking down a sprawling, multi-faceted enterprise into sub-domains that we can deal with in relative isolation, and with some degree of autonomy.

DDD can sound like a huge commitment, however contemporary agile-aligned processes (such as Event Storming) and domain modelling tooling (such as Jargon) give a lean focus and form to the discipline, and provide vehicles for sharing and collaboration on the model. In this way, the domain model “acts as a Ubiquitous Language to help communication between software developers and domain experts” Fowler, M 2014, BoundedContext.

The Domain Model

DDD addresses both strategic and tactical design. Through a process of broad stakeholder consultation, distillation and frequent iteration, it will build a comprehensive model of the domain by identifying aggregate roots and boundaries, entities and value objects, vocabulary, business events and state-lifecycles, commands and assertions, context and dependencies. It may explore existing applicable formalisms such as industry models and frameworks.

Collaborative DDD workshops are a forum for *mutual discovery, validation and agreement* on models, boundaries and business events.

“Bottom up” analysis of legacy systems can be helpful — but ONLY as a means for engineers to bring knowledge of as-is implementation into the room with other stakeholders. Collaborative DDD workshops such as Event Storming are a forum for mutual discovery, validation and agreement on models, boundaries and business events.

More on the design process: API Design Practice. A practical guide… | Medium

Model Driven Design

The domain driven design (DDD) derived Domain Model is the source of truth for the business capability implementation and the REST model, and acts as a Ubiquitous Language of communication. To this end, the model must be easily accessible to all stakeholders to interact with — maximizing collaboration, providing the tightest possible feedback loop, and ensuring that the domain model remains the definitive source-of-truth.

The process is ‘model driven’, however it is not ‘model up-front’. Domain driven design must be an iterative process, and from the outset will involve a multidisciplinary team that should certainly include the developers tasked with implementing the capability. The model must learn from the realities of implementation and must be rigorously maintained in order to capture and communicate the evolution of the model.

Security by Design

Model driven design provides an opportunity to embed security into every stage of the design process.

Ideally, data will be classified, and regulatory controls identified during the domain modelling phase. Patterns and tactics to implement security controls should described, as well as processes to validate and test API security controls against security policies.

Security by Design: A core focus of model driven design

The Business Resource

The bounded context and its aggregates (entity groups defined by consistency boundaries) will encompass one or more business capabilities — realisable as microservices. However…

“an operational system and it’s team or organizational unit, are not only responsible for providing business capabilities but also responsible for providing the truths of their business domain as source domain datasets” — Dehghani, Z 2019, Data Monolith to Mesh.

From the business information, events and processes managed by a System-of-Record business service, are abstracted one or more canonical business resources. Business resources represent the nouns of a system, such as ‘applications’ and ‘applicants’. They provide a context for interaction with a business capability, represent the business facts about a business domain, and when consistently modeled, discoverable and subscribable, they become the backbone of a federated data platform.

Harmonized API-led interoperability-as-a-platform is discussed here.

REST Model Abstraction

A REST model will describe a business resource, and how client systems interact with it. It will detail operations, methods, paths and status codes. It is a refinement and/or abstraction of the domain data model with a focus on interoperability.

“REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components” — Fielding, R.T. 2000, Representational State Transfer (REST)

Composability

Microservices architectures and the REST architectural style enable decoupling, self-service and re-use by moving the responsibility for choreography from the resource server to the client. This shift in responsibility allows business systems to build stable, genericised interfaces to their business resources and capabilities, without tight coupling to client systems, which in turn allows client systems to compose data via self-service integration without a blocking dependency on external teams.

Rather than being ‘client-centric’ (an overloaded term), business resource APIs should be ‘capability-centric’ and ‘developer-empathetic’. ‘Developer empathy’ is focused on usability and painless integration. Client and user-centricity is a feature of the business capability and is reflected in the domain models from which our REST models are derived — and these models can and should evolve over time. A System-of-Record business service owns the model and the vocabulary, and is always ‘upstream’.

Balancing Composability *with C**ohesion*

The key aims of REST model abstraction — composability, cohesion and stability — are concepts that align closely with the DDD process of distillation of the core domain and conceptual contours. If the object that represents the business capability aggregate root is overly large and complex, if the core focus of the business is not evident in the model, it is likely that the domain model requires further refinement.

“A supple design based on a deep model yields a simple set of interfaces that combine logically to make sensible statements in the ubiquitous language, and without the distraction and maintenance burden of irrelevant options.” Evans, E 2003, Domain Driven Design.

Between core domain, aggregates, entities and value objects, the REST model should not lack opportunities for granularity (responsiveness and composability), but rather should be concerned with finding a balance between granularity and cohesive units of business data likely to be of interest to client systems (though not superfluous to their needs). In short, balancing composability with cohesion. Supporting elements may be modeled as sub-resources on their own path.

Business Model Abstraction

To maximise intelligibility and utility in the enterprise context, core business models are not something to abstract away, rather, their intelligible expression is a key interoperability enabler. The REST model is a communication medium, a means of sharing core business concepts and the ubiquitous language of the domain with client developers.

In some cases, depending on the level of integration and trust, enterprise business information will need to be carefully abstracted for external clients — these should be managed as mediated services, and should not impact the core domain model.

Sub-Resources

Sub-resources are resources that are existentially dependent (should not exist without the parent, e.g. ‘specification’ does not exist without a ‘product’), are subordinate to the parent (owned by the parent, e.g. ‘address’ belongs to ‘person’), or contain key information about an existentially linked peer resource.

Keeping in mind the “conceptual contours” principle (cohesive divisions), dependent and subordinate objects modeled as sub-resources within the same API specification as the parent provides a number of advantages, including;

Readability, clarity
Transparent relationship and context, conveyed by the API path, e.g. ‘v1/products/12B34C/specification’
Composability (discrete retrieval of sub-resource data)
Controlling the impact of changes

Some sub-resources may be independently addressable, and will have their own state-lifecycle and a unique identity (and resource Id) e.g.

/v1/members/12B34C/dependents/98Y76X and in some cases.../v1/members/dependents/98Y76X

In other cases, the sub-resource will represent a value object, and will be addressed as an object, collection or singleton belonging to a resource instance, e.g.

/v1/products/12B34C/specification

The following factors strongly suggest a sub-resource model:

Entity data may be managed (POST/GET/PATCH) separately from the parent entity, and subsequent to instantiation of the parent
The data (or any more than a summary) is not always of interest to consumers of the parent resource
The data is a distinct entity with a 1:n relationship to the parent, i.e. would result in an array of indeterminate size.
The data is binary (file, image)

The general consensus is that more than 2 levels of resource identifier in a URL can make APIs difficult to understand and use. If the model calls for something more than /resource/{resourceId}/resource/{resourceId} then reconsider the composition and/or granularity of the model.

Path conventions and design patterns are covered in more detail here.

Affordances

“when a significant process or transformation in the domain is not a natural responsibility of an entity or value object”, it makes sense to… “add an operation to the model as a standalone interface declared as a service” — Evans, E 2003, Domain Driven Design.

Significant, synchronously-driven state-lifecycle transitions (as captured in the domain model) may warrant a dedicated affordance operation. This topic is covered in a little more depth here: The Engine of Application State: Aligning HATEOAS, Affordances and Business Events| Medium

Affordance operations are always verbs that describe the action in the context of a resource (or resource collection). The intent of the affordance and its context are then clear. E.g.

/v1/users/98D76C/cart/checkout/v1/subscriptions/12B34C/cancel

Filtering

Not every client system will be interested in all of the information provided by a business resource API — even if it is modelled around core business data and streamlined for composability. A predictably implemented parameter driven ‘read’ filtering model (and/or consistent HTTP QUERY method scheme) that includes field and collection filters can reduce over-fetching and enhance composability. E.g.

GET /v1/subscriptions?subscriberId=12B34C&fields=subscriptionId,nameQUERY /v1/subscriptions  {...}

Note: the relatively new cache-able, idempotent HTTP Query method remains unsupported by OpenAPI 3 at the time of writing.

Filtering conventions are discussed in more detail here.

Generating an API specification from the Model

From the REST model, the constraints provided by enterprise API design standards, and a target API specification template, it is possible to generate a prototype API specification. API security schemes are derived from matching security controls captured by the domain model against templated enterprise security patterns.

Some domain modelling tools enable definition of the REST model as a domain model layer and will generate version managed API specifications directly from the model based on templates constrained by enterprise standards.

A collaborative modelling platform and vertically integrated DevOps can help minimize friction and ensure the currency and traceability of published APIs.

API versioning strategies are discussed in more detail here.

API lifecycle management and DevOps is discussed in more detail here.

Summary

A strong enterprise commitment to domain autonomy, to capturing, validating and sharing domain models, and to a process of model driven design can deliver robust and composable business resource APIs that will form the backbone of an API-led, self-service interoperability platform.