API Architecture Cheatsheet

Note: This document is a collection of definitions from various sources (Primarily, from Eric Evans’s book on Domain-driven design and other sources from internet). The goal of the document is not train anyone on Domain-driven design or Microservices architecture, but to explain all necessary building blocks for a robust API Architecture. The document describes only a subset of concepts/terms from DDD to help building great APIs/Microservices that are business focussed and reliable. In all subsequent posts relating to the API Architecture (The API Architecture series), we’ll use/expand terms/concepts described in this post.

Core Concepts

Core Domains

A core domain is a business area/problem space that is of primary importance (and strategically important) to the success of an organization. The core domains are what the organization known for in the eyes of its customers-the core domain defines an organization’s identity/existence. All organizations MUST excel in their core domains. For example, for PayPal, Checkout and Digital Wallet are the core domains. For Facebook, the core domain is social media/Networking. For Google, the core domains are, Search, Video Sharing and social media) (YouTube), and Cloud Platform (GCP).

Supporting domains

Supporting domains are the ones that are essential to deliver the core domain’s functionality, but they are not core themselves. Supporting domains always address some areas of an organization’s business. These are strategically important for the company. The company cannot deliver/succeed in the core domains without the success in these supporting domains (equivalent to losing competitive advantage). For example, for any Payments/Fin-tech company, compliance, and risk are the examples of Supporting Domains. It is possible that some supporting domain may transition to become core domains later (For example, When AWS EC2 was initially built, the goal was to help Amazon’s e-commerce infrastructure needs, but eventually, it served non-Amazon customers and become one of the most important core businesses for Amazon.

Generic domains

Generic domains are the ones that are still essential to deliver the functionality of the Core or supporting domains but don’t capture or describe anything special about the business. For example, for most companies, areas like, Identity and access management, Customer Support, non-strategic technology platform areas, and most things that support business functions(accounting/reporting etc) are generic domains.

Sub domains

A subdomain represents a specific problem space within a domain. A subdomain adds specificity and context with a clear linguistic boundary. Subdomains are created by breaking the core/supporting/generic domains further to smaller problem spaces, for the ease of implementation. Each of core/supporting/generic domain MAY consist of many subdomains. Subdomains are essential to deliver core/supporting/generic domains. Usually, a subdomain is implemented as a bounded context.

Ubiquitous Language

A common language for the domain. It is a language structured around the domain model. Generally, the Ubiquitous language is made up of entities (and their names), value objects (and their names), services (and their names), and bounded context (and its name).

Bounded Context

A boundary where a particular domain model applies. A bounded context implements a sub domain. Each bounded context has its own Ubiquitous Language.

Relationships and Model Integrity

Context Map

A representation of all bounded contexts in various domains, the actual relationship between them, and their models.

The following actors and relationships describe a context map.

Actors

Upstream

The service provider bounded context.

Downstream

The consumer bounded context.

Relationships

Shared Kernel

The bounded contexts share the subset of the domain model with a common subset of entities/value objects etc.).

Customer-Supplier

The supplier bounded context exposes interfaces to meet the requirement of the consumer bounded context. The success of the supplier team is usually dependent on the success of the customer/consumer team.

Conformist

The supplier bounded context doesn’t care about any consumer bounded context, so a consumer bounded context is forced to integrate with the supplier bounded context on as-is basis.

Separate ways

The supplier and the consumer bounded context don’t need to integrate with each other.

Anticorruption Layer

The consumer or a supplier bounded context create an anticorruption layer to translate the domain model back and forth between the bounded contexts.

Open Host Service

The supplier bounded context exposes its services via a well-defined API. This is usually referred as OHS.

Published Language

The IDL (interface description Language) that describes the API constructs (resources, requests, responses etc.). This is usually referred as PL.

Core Object Patterns

Entities

An entity is a unique thing in a domain that is capable of being changed over a long period of time. Each Entity is identified by its unique id. An entity may comprise of one or more other entities and value objects. Entities are also called as reference objects.

Root Entities

A special entity that is a root of an Aggregate. Root entity is the only entity in an aggregate that other entities in other aggregates are allowed to hold references to.

Value Objects

A value object measure, quantify, or describe a thing in a domain. A value object doesn’t have any identifier of its own.

Services

A service is a domain operation offered as an interface that stands alone in the model with no encapsulated state of its own. To not confuse it with a Microservices, it is referred as “DDD Service”, from hereafter.

Domain Events

A domain event describes a state change of an entity in a domain. Generally speaking, in a domain, a domain event describes the state changes of an Aggreagate.

Entity Lifecycle

Aggregate

A cluster of entities, value objects that are treated as a unit for the purpose of data changes. An aggregate has a root and a boundary (defines what is inside an aggregate). All operations (and access to other entities/value objects) on the aggregate are allowed to be performed only via the aggregate root. An aggregate defines a consistency boundary. An Aggregate defines invariants (a set of consistency rules) that are maintained or applied at every stage of its lifecycle.

Object Access

Repositories

A Repository is a mechanism for encapsulating storage, retrieval, and search behavior which emulates a collection of objects. Access to Aggregates is performed via a repository. A repository may use various persistent/in-memory data sources or call other APIs to fulfill the query/write requests.

Microservice Boundaries (Also API product/capability boundary)

An Aggregate or a DDD Service is usually what determines the service boundary. A service boundary can sometimes (rarely)be as large as the bounded context. Also, other factors, such as the client use-cases/usage patterns, and non-functional requirements influence the sizing of a service boundary.

Microservice Architecture

The service architecture pattern below is based on the Ports and Adapters Architecture (aka Hexagonal Architecture). The Architecture helps isolating the domain model from various API protocols, underlying data sources, and helps it evolve independently.

Microservice Application Architecture

The pattern below describes a robust/reliable/evolutionary application architecture backed by Microservices and APIs.