,Introduction
In this introduction, you will discover the basics of APIs and their potential to be part of the
architecture journey. We will introduce a lightweight definition for APIs and their use in and out
of process. In order to demonstrate the importance of APIs, we will introduce the conference
system case study, a running example that will evolve throughout the book. Out-of-process APIs
allow you to think beyond a simple three-tiered architecture; we will introduce traffic patterns and
their importance to demonstrate this. We will outline a summary of the case study steps, allowing
you to skip ahead if an area is of interest to you straight away.
In order to present APIs and their associated ecosystem, we will use a series of important artifacts.
We will introduce the case study with C4 model diagrams and revisit the specifics and logic behind
the approach. You will also learn about the use of Architecture Decision Records (ADRs) and the
value of clearly defining decisions across the software lifecycle. As the introduction closes, we
will outline ADR Guidelines—our approach to help you make decisions when the answer is “it
depends.”
The Architecture Journey
Anyone who has taken a long journey will no doubt have encountered the question (and possibly
persistently) “are we there yet?” For the first few inquiries, you look at the GPS or a route planner
and provide an estimate—hoping that you don’t encounter any delays along the way. Similarly,
the journey to building API-based architectures can be complex for developers and architects to
navigate; even if there was an Architecture GPS, what would your destination be?
Architecture is a journey without a destination, and you cannot predict how technologies and
architectural approaches will change. For example, you may not have been able to predict service
mesh technology would become so widely used, but once you learn about its capabilities it may
cause you to think about evolving your existing architecture. It is not only technologies that
influence change in architecture; new business requirements and constraints also drive change in
architectural direction.
The culminating effect of delivering incremental value combined with new emerging technologies
leads to the concept of evolutionary architecture. Evolutionary architecture is an approach to
incrementally changing an architecture, focusing on the ability to change with speed and reducing
the risk of negative impacts. Along the way, we ask you to keep the following advice in
approaching API architecture in mind:
Though architects like to be able to strategically plan for the future, the constantly changing
software development ecosystem makes that difficult. Since we can’t avoid change, we need to
exploit it.
Building Evolutionary Architectures by Neal Ford, Rebecca Parsons, and Patrick Kua (O’Reilly)
,In many projects APIs themselves are evolutionary, requiring change as more systems and services
are integrated. Most developers have built services that focus on a single function without
considering the broader API reuse from a consumer perspective.
API-First design is an approach where developers and architects consider the functionality of their
service and design an API in a consumer-centric manner. The API consumer could be a mobile
application, another service, or even an external customer. In Chapter 1 we will review design
techniques to support an API-First approach and discover how we build APIs that are durable to
change and deliver value to a broad consumer base.
The good news is that you can start an API-driven architecture journey at any point. If you are
responsible for preexisting technical inventory, we will show you techniques to evolve your
architecture to promote the use of APIs in your platform. On the other hand, if you are lucky and
have a blank canvas to work with, we will share with you the benefit of adopting API architectures
based on our years of experience, while also highlighting key factors in decision making.
A Brief Introduction to APIs
In the field of software architecture, there are a handful of terms that are incredibly difficult to
define. The term API, which stands for application programming interface, falls into this
categorization, as the concept first surfaced as many as 80 years ago. Terms that have been around
for a significant amount of time end up being overused and having multiple meanings in different
problem spaces. We consider an API to mean the following:
An API represents an abstraction of the underlying implementation.
An API is represented by a specification that introduces types. Developers can
understand the specifications and use tooling to generate code in multiple languages
to implement an API consumer (software that consumes an API).
An API has defined semantics or behavior to effectively model the exchange of
information.
Effective API design enables extension to customers or third parties for a business
integration.
Broadly speaking, APIs can be broken into two general categories depending on whether the API
invocation is in process or out of process. The process being referred to here is an operating
system (OS) process. For example, a Java method invocation from one class to another is an in-
process API invocation, as the call is handled by the same process from which the call was made.
A .NET application invocating an external REST-like API using an HTTP library is an out-of-
process API invocation, as the call is handled by an additional external process other than the
process from which the call was made. Typically, an out-of-process API call will involve data
traversing a network, potentially a local network, virtual private cloud (VPC) network, or the
internet. We will focus on the latter style of APIs; however, architects will often encounter the
requirement to remodel an in-process API to an out-of-process API. In order to demonstrate this
concept (and others), we will create a running case study that will evolve throughout the book.
, Running Example: Conference System Case
Study
We have chosen to model a conference system for our case study because the domain is easily
recognizable but also provides enough complexity for modeling an evolutionary
architecture. Figure I-1 visualizes the conference system at the top level, allowing us to set the
context of the architecture under discussion. The system is used by an external customer to create
their attendee account, review the conference sessions available, and book their attendance.
Figure I-1. C4 conference system context diagram
Let’s zoom in to the conference system box in Figure I-2. Expanding the conference system
provides us more detail about its major technical building blocks. The customer interacts with the
web application, which invokes APIs on the conference application. The conference application
uses SQL to query the backing datastore.
Figure I-2. C4 conference system container diagram
Figure I-2 reveals that from an API perspective the most interesting functionality is within the
conference application container. Figure I-3 zooms in to this specific container, allowing you to
explore the structure and interactions.
Four major components and the database are involved in the current system. The API
Controller faces all incoming traffic from the UI and makes a decision about where to route the
request in the system. This component would also be responsible for marshaling from the on the
wire network-level representation to an object or representation in code. The API Controller
component is intriguing from the perspective of in-process routing and acting as a junction
point or front controller pattern. For API requests and processing, this is an important pattern; all
In this introduction, you will discover the basics of APIs and their potential to be part of the
architecture journey. We will introduce a lightweight definition for APIs and their use in and out
of process. In order to demonstrate the importance of APIs, we will introduce the conference
system case study, a running example that will evolve throughout the book. Out-of-process APIs
allow you to think beyond a simple three-tiered architecture; we will introduce traffic patterns and
their importance to demonstrate this. We will outline a summary of the case study steps, allowing
you to skip ahead if an area is of interest to you straight away.
In order to present APIs and their associated ecosystem, we will use a series of important artifacts.
We will introduce the case study with C4 model diagrams and revisit the specifics and logic behind
the approach. You will also learn about the use of Architecture Decision Records (ADRs) and the
value of clearly defining decisions across the software lifecycle. As the introduction closes, we
will outline ADR Guidelines—our approach to help you make decisions when the answer is “it
depends.”
The Architecture Journey
Anyone who has taken a long journey will no doubt have encountered the question (and possibly
persistently) “are we there yet?” For the first few inquiries, you look at the GPS or a route planner
and provide an estimate—hoping that you don’t encounter any delays along the way. Similarly,
the journey to building API-based architectures can be complex for developers and architects to
navigate; even if there was an Architecture GPS, what would your destination be?
Architecture is a journey without a destination, and you cannot predict how technologies and
architectural approaches will change. For example, you may not have been able to predict service
mesh technology would become so widely used, but once you learn about its capabilities it may
cause you to think about evolving your existing architecture. It is not only technologies that
influence change in architecture; new business requirements and constraints also drive change in
architectural direction.
The culminating effect of delivering incremental value combined with new emerging technologies
leads to the concept of evolutionary architecture. Evolutionary architecture is an approach to
incrementally changing an architecture, focusing on the ability to change with speed and reducing
the risk of negative impacts. Along the way, we ask you to keep the following advice in
approaching API architecture in mind:
Though architects like to be able to strategically plan for the future, the constantly changing
software development ecosystem makes that difficult. Since we can’t avoid change, we need to
exploit it.
Building Evolutionary Architectures by Neal Ford, Rebecca Parsons, and Patrick Kua (O’Reilly)
,In many projects APIs themselves are evolutionary, requiring change as more systems and services
are integrated. Most developers have built services that focus on a single function without
considering the broader API reuse from a consumer perspective.
API-First design is an approach where developers and architects consider the functionality of their
service and design an API in a consumer-centric manner. The API consumer could be a mobile
application, another service, or even an external customer. In Chapter 1 we will review design
techniques to support an API-First approach and discover how we build APIs that are durable to
change and deliver value to a broad consumer base.
The good news is that you can start an API-driven architecture journey at any point. If you are
responsible for preexisting technical inventory, we will show you techniques to evolve your
architecture to promote the use of APIs in your platform. On the other hand, if you are lucky and
have a blank canvas to work with, we will share with you the benefit of adopting API architectures
based on our years of experience, while also highlighting key factors in decision making.
A Brief Introduction to APIs
In the field of software architecture, there are a handful of terms that are incredibly difficult to
define. The term API, which stands for application programming interface, falls into this
categorization, as the concept first surfaced as many as 80 years ago. Terms that have been around
for a significant amount of time end up being overused and having multiple meanings in different
problem spaces. We consider an API to mean the following:
An API represents an abstraction of the underlying implementation.
An API is represented by a specification that introduces types. Developers can
understand the specifications and use tooling to generate code in multiple languages
to implement an API consumer (software that consumes an API).
An API has defined semantics or behavior to effectively model the exchange of
information.
Effective API design enables extension to customers or third parties for a business
integration.
Broadly speaking, APIs can be broken into two general categories depending on whether the API
invocation is in process or out of process. The process being referred to here is an operating
system (OS) process. For example, a Java method invocation from one class to another is an in-
process API invocation, as the call is handled by the same process from which the call was made.
A .NET application invocating an external REST-like API using an HTTP library is an out-of-
process API invocation, as the call is handled by an additional external process other than the
process from which the call was made. Typically, an out-of-process API call will involve data
traversing a network, potentially a local network, virtual private cloud (VPC) network, or the
internet. We will focus on the latter style of APIs; however, architects will often encounter the
requirement to remodel an in-process API to an out-of-process API. In order to demonstrate this
concept (and others), we will create a running case study that will evolve throughout the book.
, Running Example: Conference System Case
Study
We have chosen to model a conference system for our case study because the domain is easily
recognizable but also provides enough complexity for modeling an evolutionary
architecture. Figure I-1 visualizes the conference system at the top level, allowing us to set the
context of the architecture under discussion. The system is used by an external customer to create
their attendee account, review the conference sessions available, and book their attendance.
Figure I-1. C4 conference system context diagram
Let’s zoom in to the conference system box in Figure I-2. Expanding the conference system
provides us more detail about its major technical building blocks. The customer interacts with the
web application, which invokes APIs on the conference application. The conference application
uses SQL to query the backing datastore.
Figure I-2. C4 conference system container diagram
Figure I-2 reveals that from an API perspective the most interesting functionality is within the
conference application container. Figure I-3 zooms in to this specific container, allowing you to
explore the structure and interactions.
Four major components and the database are involved in the current system. The API
Controller faces all incoming traffic from the UI and makes a decision about where to route the
request in the system. This component would also be responsible for marshaling from the on the
wire network-level representation to an object or representation in code. The API Controller
component is intriguing from the perspective of in-process routing and acting as a junction
point or front controller pattern. For API requests and processing, this is an important pattern; all
