Application Network Design

Anypoint Platform Architecture

MuleSoft Training
2017-11-01
Table of Contents
Welcome To Anypoint Platform Architecture: Application Network Design 1
1. Putting the Course in Context 9
2. Introducing MuleSoft, the Application Network Vision and Anypoint Platform 15
3. Establishing Organizational and Platform Foundations 32
4. Identifying, Reusing and Publishing APIs 48
5. Enforcing NFRs on the Level of API Invocations Using Anypoint API Manager 75
6. Designing Effective APIs 100
7. Architecting and Deploying Effective API Implementations 125
8. Augmenting API-Led Connectivity With Elements From Event-Driven Architecture 143
9. Transitioning Into Production 153
10. Monitoring and Analyzing the Behavior of the Application Network 166
Wrapping-Up Anypoint Platform Architecture: Application Network Design 184
Appendix A: Documenting the Architecture Model 187
Appendix B: ArchiMate Notation Cheat Sheets 191
Glossary 194
Bibliography 206
Version History 207
Anypoint Platform Architecture Application Network Design

Welcome To Anypoint Platform Architecture:

Application Network Design

Introducing the course

Course prerequisites
The target audience of this course are architects, especially Enterprise Architects and Solution
Architects, new to Anypoint Platform, API-led connectivity and the application network, but
experienced in other integration approaches (e.g., SOA) and integration
technologies/platforms.

Prior to attending this course, students are required to get an overview of Anypoint Platform
and its constituent components. This can be achieved by various means, such as

• attending the short Getting Started with Anypoint Platform course

• attending the much more thorough developer-centric courses Anypoint Platform
Development: Fundamentals or MuleSoft.U Development Fundamentals
• participating in the 1-day hands-on "API-Led Connectivity Workshop" organized by MuleSoft
Presales upon request

Course goals
The overarching goal of this course is to enable students to

• direct the emergence of an effective application network out of individual integration

solutions following API-led connectivity, working with all relevant stakeholders on all levels
of the organization
• create credible high-level architecture models for integration solutions on Anypoint Platform
such that functional and non-functional requirements are likely to be met and the principles
of API-led connectivity and application networks are followed

Course objectives
These high-level goals are broken-down into the following objectives:

• Conceptualize integration capability delivery holistically along the six dimensions

(playbooks) of Outcome-Based Delivery (OBD): business outcomes, platform, projects,
Center for Enablement (C4E), internal support, training. [U/A]
• Advise in the establishment and operation of a C4E. [U/A]

© 2017 MuleSoft Inc. 1

Anypoint Platform Architecture Application Network Design

• Select the deployment options for Anypoint Platform that most effectively support an
organization’s priorities. [A/E]
• Break down the functional requirements of strategic organizational initiatives first into
products and then into business-aligned, versioned APIs with effective granularity and API
data model, following the principles of API-led connectivity. [C]
• Direct the creation and publication of API-related assets using RAML and Anypoint Platform
components and features (such as Anypoint API Manager, API designer, API Notebooks, API
Portals, API Consoles, Anypoint Exchange) with the goal of maximizing not only their value
for a given project but also their wider consumption (incl. by API consumers and operations
teams) to further the growth of the application network. [A/E]
• Identify non-functional requirements that are best addressed on the level of API invocations
and architect for their effective documentation, implementation, enforcement, analysis,
monitoring and alerting using HTTP, RAML and components and features of Anypoint
Platform (such as CloudHub Load Balancers and CloudHub Dedicated Load Balancers,
Anypoint API Manager, API policies, API proxies and Anypoint Analytics). [C]
• Identify non-functional requirements that are best addressed on the level of API
implementations and/or API clients and architect for their effective implementation,
deployment, monitoring and alerting using components and features of Anypoint Platform
(such as CloudHub, the Mule runtime, Anypoint MQ and Anypoint Runtime Manager). [C]
• Select API policies, their enforcement in API proxies or within API implementations, and
define monitoring and alerting approaches in accordance with the principles of API-led
connectivity. [A/E]
• Architect for specific requirements by augmenting API-led connectivity with elements from
Event-Driven Architecture using Anypoint MQ. [A/E]
• Advise organizations on their general approach to DevOps, CI/CD and testing of API-led
connectivity solutions within an application network, making effective use of the automation
capabilities of Anypoint Platform. [U/A]

Each of these objectives is assigned to a level in Bloom’s revised taxonomy:

[R]
Remembering

[U/A]
Understanding and applying

[A/E]
Analyzing and evaluating

© 2017 MuleSoft Inc. 2

Anypoint Platform Architecture Application Network Design

[C]
Creating

Course outline
• Welcome To Anypoint Platform Architecture: Application Network Design
• Module 1
• Module 2
• Module 3
• Module 4
• Module 5
• Module 6
• Module 7
• Module 8
• Module 9
• Module 10
• Wrapping-Up Anypoint Platform Architecture: Application Network Design

How the course will work

This is a course on Enterprise Architecture with elements of Solution Architecture:

• It discusses topics on the scale of Enterprise Architecture, touching lightly on Business

Architecture, and heavily on Application Architecture and Technology Architecture.
• It motivates and builds Enterprise Architecture from strategically important integration
solutions and therefore elaborates on parts of their high-level Solution Architecture.
• It stays away from architecturally insignificant design and implementation discussions:
◦ As a rule, these are all topics whose repercussions are confined to individual application
components and are therefore not apparent from outside these application components.
◦ When a decision affects the large-scale properties of the application network, however, it
becomes architecturally significant. This is the reason why the course contains a fairly
detailed discussion on strategies for invoking APIs in a fault-tolerant way (see Section
7.2).
• No code is shown, neither implementation code nor code for API specifications such as
RAML definitions. However, the topic of API specifications and the features offered by RAML
in this space are touched upon in several places, because they are important for the
functioning of an application network.

© 2017 MuleSoft Inc. 3

Anypoint Platform Architecture Application Network Design

This course is primarily driven by a single case study, Acme Insurance, and two imminent
strategically important change initiatives that need to be addressed by Acme Insurance. These
change initiatives provide the background and motivation for most discussions in this course.

As various aspects of the case study are addressed, the discussion naturally elaborates on the
central topic of the course, i.e., how to architect and design application networks using API-led
connectivity and Anypoint Platform.

However, the course cannot jump into architecting without any prior knowledge about
Anypoint Platform, what terms like "API-led connectivity" and "application network" actually
mean, and how MuleSoft and MuleSoft customers typically approach integration challenges like
those faced by Acme Insurance. Therefore, Module 1 and Module 2 provide this context-setting
and introduction. Acme Insurance itself is briefly introduced already in Introducing Acme
Insurance and becomes the focus of the discussion from Module 3 onwards.

As the architectural and design discussions in this course unfold, it is inevitable that opinions
are expressed, solutions presented and decisions made that are somewhat ambiguous, without
a clear-cut distinction between correct or false: such is the nature of architecture and design.
A good example of this is the discussion on Bounded Context Data Model versus Enterprise
Data Model in section Section 6.3. Students are of course encouraged to challenge the
decisions made, and to decide differently in similar real-world situations. The crucial point is
that the thought processes behind these architectural and design decisions are elaborated-on
in the course, which creates awareness of the topic and increases understanding of the
tradeoffs involved in making a decision.

Exercises, typically in the form of group discussions, are an important element of this course.
But these exercises are never in the form of actually doing something, on the computer, with
Anypoint Platform or any of its components. Instead, they are simply discussions that invite to
reflect, with the intention of validating and deepening the understanding of a topic addressed
in the course.

All architecture diagrams use ArchiMate 3 notation. A summary of that notation can be found
in Appendix B.

Course logistics
• Class is from 09:00 to 17:00
• 1 hour lunch break, approx. from 12:30 to 13:30
• 15 minute break each morning and afternoon
◦ Other breaks as desired - just ask!
• Please let us know if you have other business to attend to!

© 2017 MuleSoft Inc. 4

Anypoint Platform Architecture Application Network Design

Course materials and certification

Students receive the Course Manual (this document), a PDF of approx. 200 pages, containing
all material presented on slides plus additional discussions and explanations.

The course manual is somewhere between a bound edition of the slides and a standalone
book: it contains all slide content and enough context around this content to be much easier to
consume than the slides alone would be. On the other hand, the course manual lacks some of
the explanations and elaborations that a full-fledged book would be expected to contain: this
additional depth is provided by the instructor when teaching the course!

MuleSoft offers a certification based on this course: "MuleSoft Certified Architect (MCA) -
Application Network Designer". For the target audience of this course, attending class and
studying the Course Manual should be sufficient for passing the exam.

Introducing Acme Insurance

The Acme Insurance organization

Acme Insurance is a well-established, medium-sized, nation-wide insurance provider. They
have two lines of business (LoBs): personal motor insurance and home insurance.

Acme Insurance has recently been acquired by an international competitor: The New Owners.
As one consequence, Acme Insurance is currently being rebranded as a national subsidiary of
The New Owners. As another important consequence, Acme Insurance’s strategy is
increasingly being defined by The New Owners.

The New
Owners

Acme Corporate HQ Other

Insurance HQ Acquisitions'
HQs

Personal Home LoB Acme IT Corporate IT

Motor LoB

Personal Motor Claims Motor Home Home Claims Home LoB IT

Motor LoB IT Underwriting Underwriting

Figure 1. Relevant elements of the organizational structure of Acme Insurance

© 2017 MuleSoft Inc. 5

Anypoint Platform Architecture Application Network Design

A glimpse into Acme Insurance's baseline Technology

Architecture
The baseline Technology Architecture of Acme Insurance can, at a very high level, be
characterized as follows (see Figure 2):

• Acme Insurance operates an IBM-centric Data Center with the Acme Insurance Mainframe
and clusters of AIX machines
• The Policy Admin System runs on the Mainframe and is used by both Motor and Home
Underwriting. However, support for Motor and Home policies was added to the Policy Admin
System in different phases and so uses different data schemata and database tables
• The Motor Claims System is operated in-house on a WebSphere application server cluster
deployed on AIX
• The Home Claims System is a different system, operated by an external hosting provider
and accessed over the web
• Both claims systems are accessed by Acme Insurance’s own Claims Adjudication team from
their workstations
• Simple claims administration is handled by an outsourced call center, also via the Motor
Claims System and Home Claims System

Outsourced Call Center

Motor Claims Home Claims

Admin Admin
Workstations Workstations

Backoffice

Motor Home Claims

Underwriting Underwriting Adjudication
Workstations Workstations Workstations

Acme Insurance Data Center Outsourcing Hosting Provider

Mainframe WebSphere AIX Cluster VPN Unspecified Infrastructure

Policy Admin Rating Engine Motor Claims Home Claims

System System System

Figure 2. A small sub-set of the baseline Technology Architecture of Acme Insurance

© 2017 MuleSoft Inc. 6

Anypoint Platform Architecture Application Network Design

Acme Insurance's motivation to change

Under pressure from The New Owners, Acme Insurance executives embark on two immediate
strategic initiatives (see Figure 3):

• Open-up to external price comparison services ("Aggregators") for motor insurance: This
contributes to the goal of establishing new sales channels, which in turn (positively)
influences the driver of increasing revenue, which is important to all management
stakeholders
• Provide (minimal) self-service capabilities to customers: This contributes to the goal of
increasing the prevalence of customer self-service, which in turn (positively) influences the
driver of reducing cost, which is important to all management stakeholders as well as to
Corporate IT

Not immediately relevant, but clearly on the horizon, are the following far-reaching changes:

• Replace the two bespoke claims handling systems, the Motor Claims System and Home
Claims System, with one COTS product: This contributes to the principle of preferring COTS
solutions, which in turn contributes to Corporate IT’s goal of standardizing IT systems
across all subsidiaries of The New Owners
• Replace the legacy policy rating engine with a corporate standard: This contributes to the
principle of reusing custom software (such as the corporate standard policy rating engine)
where possible, which in turn contributes to Corporate IT’s goal of standardizing IT systems

© 2017 MuleSoft Inc. 7

Anypoint Platform Architecture Application Network Design

Acme The New Corporate IT

Insurance Owners
Execs

Revenue Cost
Increase Reduction

New Sales Customer IT System

Channels Self-Service Standardization

Prefer COTS Reuse

Custom
Software

Open to Provide Self- Replace Replace

Aggregators Service Claims Rating
Capabilities Systems Engine

Figure 3. Acme Insurance's immediate and near-term strategic change initiatives, their
rationale and stakeholders

© 2017 MuleSoft Inc. 8

Anypoint Platform Architecture Application Network Design

Chapter 1. Putting the Course in Context

Objectives
• Know about Outcome-Based Delivery (OBD)
• Understand how this course is aligned to parts of OBD
• Use essential course terminology correctly
• Become familiar with the ArchiMate 3 notation subset used in this course

1.1. Understanding the course organization

1.1.1. Introducing Outcome-Based Delivery - OBD

OBD is a framework and methodology for enterprise integration delivery proposed by
MuleSoft. It takes a holistic view of delivering integration capabilities, addressing

• Business outcomes, incl. alignment and governance of integration capability delivery

• Technology delivery, separating
◦ cross-project platform concerns
◦ from the delivery of projects
• Organizational enablement, specifically
◦ the establishment of a Center for Enablement in the organization
◦ the professional IT support for Anypoint Platform with the help of the MuleSoft support
organization
◦ training of all staff involved in delivering integration capabilities

© 2017 MuleSoft Inc. 9

Anypoint Platform Architecture Application Network Design

Figure 4. OBD holistically addresses all aspects of integration capability delivery into an
organization

1.1.2. Course content in the context of OBD

OBD is materialized by "playbooks", where each playbook addresses one of the dimensions of
OBD and identifies activites along that dimension. This course is aligned with the principles of
OBD and the OBD playbooks, but it does not follow the exact naming or sequential order of
the playbooks' activities.

Being an architecture course, it focuses on these dimensions of OBD:

• Technology delivery, both from an Anypoint Platform and projects perspective

• Organizational enablement through the C4E

However:

• Iteration is at the heart of OBD, but this course does not iterate
◦ Every topic is discussed once, in the light of different aspects of the case study, which
would in the real world be addressed in different iterations
• OBD stresses planning, but this course does not simulate planning activities or present
plans
• Discussion of organizational enablement and the C4E is light and mainly introduces the
concept and a few ideas on how to measure the C4E’s impact with KPIs

© 2017 MuleSoft Inc. 10

Anypoint Platform Architecture Application Network Design

Figure 5. This course focuses on architectural aspects of technology delivery and introduces
the C4E

1.2. Understanding essential course terminology

1.2.1. Defining API

See the corresponding glossary entry, cf. Figure 6.

1.2.2. Defining API client

See the corresponding glossary entry.

1.2.3. Defining API consumer

See the corresponding glossary entry.

1.2.4. Defining API implementation

See the corresponding glossary entry.

1.2.5. Defining API-led connectivity

See the corresponding glossary entry.

© 2017 MuleSoft Inc. 11

Anypoint Platform Architecture Application Network Design

1.2.6. Simplified notion of API

In colloquial usage of the term API, departing from the precise definition given in Section
1.2.1, API often refers not just to the application interface but to the combination of

• a programmatic application interface

◦ i.e., the precise meaning of API
• the application service to which this application interface provides access
• the business service realized by that application service
• the HTTP-based technology interface realizing the application interface in concrete technical
terms
• and, importantly, the application component implementing the functionality exposed by the
application interface
◦ i.e., the API implementation
• See Figure 6, cf. Figure 128

Simplified
notion of API

API Client

Figure 6. The simplified notion of API merges the aspects of application interface, technology
interface, API implementation, application service and business service and is here
represented visually as an application service element with the name of the API. An API in this
simplified sense serves an API client and is invoked (triggered) by that API client

This simplified notion of API is justified because in a very significant number of cases there is
exactly one instance of each of these elements per API.

Using this simplified notion of API:

• Experience APIs are shown invoking Process APIs and Process APIs are shown invoking
System APIs, although, in reality, it is only the API implementation of the Experience API
that depends on the technology interface of the Process API and, at runtime, through that
interface, invokes the API implementation of the Process API; and only the API
implementation of the Process API that depends on the technology interface of the System

© 2017 MuleSoft Inc. 12

Anypoint Platform Architecture Application Network Design

API and, at runtime, through that interface, invokes the API implementation of the System
API
• It is possible to say that an “API is deployed to a runtime” when in reality it is only the API
implementation (the application component) that is deployable

In other contexts (not in this course), the terms "service" or "microservice" are used for the
same purpose as the simplified notion of API.

When the simplified notion of API is dominant then the pleonasm "API interface" is sometimes
used to specifically address the interface-aspect of the API in contrast to its implementation-
aspect.

For instance:

• If the Auto policy rating API were just exposed over one HTTP-based interface, e.g., a
JSON/REST interface, then the simplified notion of this API would comprise:
◦ Technology interface: Auto policy rating JSON/REST programmatic interface
◦ Application interface: Auto policy rating
◦ Business service: Auto policy rating
◦ The application component (API implementation) implementing the exposed functionality
• However, since the Auto policy rating API (in the strict sense of application interface) is also
realized by a second technology interface, the Auto policy rating SOAP programmatic
interface, it is not clear whether the simplified notion of API comprises both technology
interfaces or not. It is therefore preferred, in complex cases such as this, to use the term
API only in its precise sense, i.e., as a special kind of application interface as defined in
Section 1.2.1.

1.2.7. Defining application network

See the corresponding glossary entry.

Summary
• Outcome-based Delivery (OBD) is a holistic framework and methodology for enterprise
integration delivery proposed by MuleSoft, addressing
◦ Business outcomes
◦ Technology delivery in the form of platform delivery and delivery of projects
◦ Organizational enablement through the Center for Enablement (C4E), support for
Anypoint Platform and training

© 2017 MuleSoft Inc. 13

Anypoint Platform Architecture Application Network Design

• This course is aligned with the technology delivery and C4E aspects of OBD
• An API is an application interface, typically with a business purpose, to programmatic API
clients using HTTP-based protocols
• Sometimes API also denotes the API implementation, i.e., the underlying application
component that implements the API’s functionality
• API-led connectivity is a style of integration architecture that prioritizes APIs and assigns
them to three tiers
• Application network is the state of an Enterprise Architecture that emerges from the
application of API-led connectivity and fosters governance, discoverability, consumability
and reuse

© 2017 MuleSoft Inc. 14

Anypoint Platform Architecture Application Network Design

Chapter 2. Introducing MuleSoft, the Application

Network Vision and Anypoint Platform

Objectives
• Understand MuleSoft’s mission
• Understand MuleSoft’s proposal for closing the increasing IT delivery gap
• Learn about Anypoint Platform, its capabilities and high-level components
• Understand options for hosting Anypoint Platform and provisioning Mule runtimes

2.1. Introducing MuleSoft

2.1.1. MuleSoft's mission

MuleSoft has been on a mission since 2003 to connect the world’s applications, data and
devices. MuleSoft started solving the classic on-premises backend integration problems with
an open source, light weight ESB: Mule ESB. Since then, MuleSoft has grown to provide a
comprehensive platform to help companies with today’s business challenges.

MuleSoft mission statement:

To connect the world’s applications, data and devices to transform business

MuleSoft’s mission is to enable companies to transform and compete in a vastly changing

digital world.

2.1.2. The story behind the name

Frustrated by integration "donkey work", Ross Mason, VP Product Strategy, founded the open
source Mule project in 2003. He created a new platform that emphasized ease of development
with quick and efficient assembly of components, instead of custom-coding by hand.

2.1.3. MuleSoft customers

• More than 175,000 developers worldwide
• More than 1000 customers
• 4 of the top 10 global auto companies
• 4 of the top 9 global banks

© 2017 MuleSoft Inc. 15

Anypoint Platform Architecture Application Network Design

• 2 of the top 5 global retailers

2.1.4. Company overview

• Company
◦ Founded in 2006, HQ: San Francisco
◦ 1000+ employees worldwide
◦ Nearly 70% new subscription bookings driven by APIs, mobile and SaaS integration
• Products
◦ MuleSoft’s Anypoint Platform addresses on-premises, cloud and hybrid integration use
cases with scale and ease-of-use
◦ Subscription model with various packaged options to serve different use cases

2.2. Introducing the application network vision

2.2.1. 10-year turnover in Fortune 500 companies

There is a convergence of forces – mobile, SaaS, Cloud, Big Data, IoT and Social - is causing a
major need for a change in speed to remain competitive and/or lead the market.

It used to be that 80% of companies on the Fortune 500 would still be there after a decade.
Today, with these forces, enterprises have no better than a 1-in-2 chance of remaining in the
Fortune 500.

Figure 7. Fortune 500 10-year turnover

To succeed, companies need to be driving a very different clock speed and embrace change;
change has become a constant. Successful companies are leveraging the aforementioned
forces to be competitive and in some cases dominate their markets.

© 2017 MuleSoft Inc. 16

Anypoint Platform Architecture Application Network Design

Business is pushing to move at much faster speeds than IT and technology are able to.
Technology and IT are holding back business rather than enabling it.

MuleSoft is helping 1000+ enterprise customers undertake transformative changes, and so

have a unique perspective on the market. MuleSoft’s customers' CIOs say that they have to
achieve 3-5 times higher speed as a business within the next 2-3 years to compete.

2.2.2. Digital pressures create a widening IT delivery gap

While IT delivery capacity remains nearly constant, the compound effect of the
aforementioned forces (mobile, SaaS, Cloud, Big Data, etc.) leads to ever-increasing demands
on IT. The result is a widening IT delivery gap.

Figure 8. Illustration of the widening IT delivery gap caused by various forces

2.2.3. Current responses are insufficient

Current responses to that widening IT delivery gap are not sufficient:

• Working harder is not sustainable

• Over-outsourcing exacerbates the situation
• Agile and DevOps are important and helpful but not sufficient

2.2.4. Learning from other industries

Companies such as

• McDonald’s
• Subway
• Marriot
• Amazon

© 2017 MuleSoft Inc. 17

Anypoint Platform Architecture Application Network Design

have shown the value of these approaches:

• Create scale through reuse

• Enable self-service
• Encourage innovation "at the edge"
• Promote quality
• Retain visibility and control

2.2.5. Closing the delivery gap with constant IT delivery

capacity
MuleSoft proposes an IT operating model that takes these successful approaches from other
industries on board:

• Even with constant IT delivery capacity, IT can empower "the edge" - i.e., LoB IT and
developers - by creating assets and helping to create assets they require.
• Consumption of those assets and the innovation enabled by those assets can then occur
outside of IT, at the edge, and therefore grow at a considerably faster rate than IT delivery
capacity itself.
• In this way, the ever-increasing demands on IT can be met even though IT delivery
capacity stays approximately constant.

Figure 9. How MuleSoft's proposal for an IT operating model that distinguishes between
enablement and asset production on the one hand, and consumption of those assets and
innovation on the other hand, allows the increasing demands on IT to be met at constant IT
delivery capacity

2.2.6. An operating model that emphasizes consumption

IT is now the steward of this operating model with a virtuous cycle in which IT produces
reusable assets and enables consumption of those assets by making them discoverable and
self-served, by LoB IT and developers, while monitoring feedback and usage.

© 2017 MuleSoft Inc. 18

Anypoint Platform Architecture Application Network Design

Central IT needs to move away from trying to deliver all IT projects themselves and start
building reusable assets to enable the business to deliver some of their own projects.

Figure 10. An IT operating model that emphasizes the consumption of assets by LoB IT and
developers as much as the production of these assets

• The key to this strategy is to emphasize consumption as much as production

• Traditional IT approaches (for example, SOA) focused exclusively on production for the
delivery of projects
• In this operating model, IT changes its mindset to think about producing assets that will be
consumed by others in lines of business
• The assets need to be discoverable and developers need to be enabled to self-serve them in
projects
• The virtuous part of the cycle is to get active feedback from the consumption model along
with usage metrics to inform the production model

2.2.7. The modern API as a core enabler of this operating

model
In the proposed operating model, the organization packages-up core IT assets and capabilities
in the modern API.

The modern API is a product and it has its own software development lifecycle (SDLC)
consisting of design, test, build, manage, and versioning and it comes with thorough
documentation to enable its consumption.

• Modern APIs adhere to standards (typically HTTP and REST), that are developer-friendly,
easily accessible and understood broadly

© 2017 MuleSoft Inc. 19

Anypoint Platform Architecture Application Network Design

• They are treated more like products than code

• They are designed for consumption for specific audiences (e.g., mobile developers)
• They are documented and versioned
• They are secured, governed, monitored and managed for performance and scale

Figure 11. Visualization of how a modern API, productized with the API consumer in mind,
gives various types of API clients access to backend systems

This approach is different from SOA in these respects:

• Modern APIs are easier to consume than WS-* web services

• SOA was built by IT and for the consumption by IT only
• The technology was hard: One can’t just give the extended organization access to WS-*
web services, they wouldn’t be able to use it
◦ Not discoverable and consumable by broad developer teams within the ecosystem,
including mobile developers
• This left organizations with IT still being the bottleneck
• However, when an organization has a good SOA strategy in place, it will accelerate the
value of what API-led connectivity provides.

2.2.8. The API-led connectivity approach

API-led connectivity is a methodical way to connect data to applications through a series of
reusable and purposeful modern APIs that are each developed to play a specific role – unlock
data from systems, compose data into processes, or deliver an experience.

API-led connectivity provides an approach for connecting and exposing assets through APIs. As
a result, these assets become discoverable through self-service without losing control.

© 2017 MuleSoft Inc. 20

Anypoint Platform Architecture Application Network Design

Figure 12. An example of an integration architecture following API-led connectivity principles

by assigning APIs to the tiers of System APIs, Process APIs and Experience APIs

• System APIs: In the example, data from SAP, Salesforce and ecommerce systems is
unlocked by putting APIs in front of them. These form a System API tier, which provides
consistent, managed, and secure access to backend systems.
• Process APIs: Then, one builds on the System APIs by combining and streamlining
customer data from multiple sources into a "Customers" API (breaking down application
silos). These Process APIs take core assets and combine them with some business logic to
create a higher level of value. Importantly, these higher-level objects are now useful assets
that can be further reused, as they are APIs themselves.
• Experience APIs: Finally, an API is built that brings together the order status and history,
delivering the data specifically needed by the Web app. These are Experience APIs that are
designed specifically for consumption by a specific end-user app or device. These APIs allow
app developers to quickly innovate on projects by consuming the underlying assets without
having to know how the data got there. In fact, if anything changes to any of the systems
of processes underneath, it may not require any changes to the app itself.

With API-led connectivity, when tasked with a new mobile app, there are now reusable assets
to build on, eliminating a lot of work. It is now much easier to innovate.

2.2.9. Focus and owners of APIs in different tiers

The organizational approach to API-led connectivity empowers the entire organization to
access their best capabilities in delivering applications and projects through modern APIs that
are developed by the teams that are best equipped to do so due to their roles and knowledge
of the systems they unlock, or the processes they compose, or the experience they’d like to
offer in the application.

• Central IT produces reusable assets, and in the process unlocks key systems, including
legacy applications, data sources, and SaaS apps. Decentralizes and democratizes access to

© 2017 MuleSoft Inc. 21

Anypoint Platform Architecture Application Network Design

company data. These assets are created as part of the project delivery process, not as a
separate exercise.
• LOB IT and Central IT can then reuse these API assets and compose process level
information
• App developers can discover and self-serve on all of these reusable assets, creating the
experience-tier of APIs and ultimately the end-applications

It is critical to connect the three tiers as driving the production and consumption model with
reusable assets, which are discovered and self-served by downstream IT and developers.

Figure 13. The APIs in each of the three tiers of API-led connectivity have a specific focus and
are typically owned by different groups

• API-led connectivity is not an architecture in itself, it is an approach to encourage to unlock

assets and drive reuse and self service
• API-led connectivity is not just about technology, but is a way to organize people and
processes for efficiencies within the organization
• The APIs depicted in those tiers are actually building blocks that encapsulate connectivity,
business logic, and an interface through which others interact. These building blocks are
productized, fully tested, automatically governed, and fully managed with policies.
• Easy publishing and discovery of APIs is crucial

2.2.10. Anypoint Platform and organizational enablement

© 2017 MuleSoft Inc. 22

Anypoint Platform Architecture Application Network Design

Figure 14. The components of Anypoint Platform sit on a foundation of organizational

enablement, of which the C4E is one important element. MuleSoft offers various engagement
models to help enable organizations

2.2.11. Application landscape at the start of the journey

towards the application network

Figure 15. Isolated backend systems before the first project following API-led connectivity

2.2.12. Every project adds value to the application network

© 2017 MuleSoft Inc. 23

Anypoint Platform Architecture Application Network Design

Figure 16. Every project following API-led connectivity not only connects backend systems but
contributes reusable APIs and API-related assets to the application network

2.2.13. The application network emerges

An application network is built ground-up over time and emerges as a powerful by-product of
API-led connectivity. See Figure 131.

The assets in an application network should be

• discoverable
• self-service
• consumable by the broader organization

Nodes in the application network create new business value.

The application network is recomposable: it is built for change because it "bends but does not
break".

2.3. Highlighting important capabilities needed to

realize application networks

2.3.1. High-level technology delivery capabilities

To perform API-led connectivity an organization has to have a certain set of capabilities, some
of which are provided by Anypoint Platform:

• API design and development

◦ I.e., the design of APIs and the development of API clients and API implementations
• API runtime execution and hosting

© 2017 MuleSoft Inc. 24

Anypoint Platform Architecture Application Network Design

◦ I.e., the deployment and execution of API clients and API implementations with certain
runtime characteristics
• API operations and management
◦ I.e., operations and management of APIs and API policies, API implementations and API
invocations
• API consumer engagement
◦ I.e., the engagement of developers of API clients and the management of the API clients
they develop

As was also mentioned in the context of OBD in Section 1.1.1, these capabilities are to be
deployed in such a way as to contribute to and be in alignment with the organization’s
(strategic) goals, drivers, outcomes, etc..

These technology delivery capabilities are furthermore used in the context of an (IT) operating
model that comprises various functions.

Organisation IT-Business Strategy

Principles Drivers Outcomes Requirements Constraints

Business Outcomes Alignment

API-led Connectivity Technology Delivery Capability

Anypoint
Platform

API design API runtime API operations API consumer

and execution and engagement
development and hosting management

Operating Model
Delivery Architecture Governance Security

Figure 17. A high-level view of the technology delivery capabilities provided by Anypoint
Platform in the context of various relevant aspects of the Business Architecture of an
organization

2.3.2. Medium-level technology delivery capabilities

Figure 18 unpacks the technology delivery capabilities introduced at a high level in Figure 17.

© 2017 MuleSoft Inc. 25

Anypoint Platform Architecture Application Network Design

Rather than going into a lot of detail now, it is best to just browse through these and revisit
them at the end of the course, matching what was discussed during the course against these
capabilities.

Business Outcomes Alignment

API-led Connectivity Technology Delivery Capability

Anypoint
Platform
API design and API runtime execution and API operations and API consumer
development hosting management engagement

Development API Proxy Runtime API Versioning API Catalog and

Accelerators Hosting Portals

Runtime High-
Reusable Assets availability and Runtime Analytics API Actionable
Discovery Scalability and Monitoring Documentation
Supporting
Capabilities
API Specification API Analytics API Consumer and
Design API Implementation relevant to Client On-boarding
Runtime Hosting Operator/Provider Software
Development
API Implementation Data API Client Process
Design Transformation API Policy Credentials
Configuration and Management
Project
Management
Management
Artifacts Version Orchestration, API Analytics
Control Routing and Flow API Policy Alerting, relevant to
Control Analytics and Consumer
Reporting
Infrastructure
API Testing, Connectivity with Operations
Simulation and External Systems API Usage and
Mocking Discoverability
Analytics
Automated Build Runtime High-
Pipeline availability and
Scalability

Operating Model

Figure 18. A medium-level drill-down into the technology delivery capabilities provided by
Anypoint Platform, and some generic supporting capabilities needed for performing API-led
connectivity

2.3.3. Introducing important derived capabilities related to API

clients and API implementations
API clients and API implementations are application components. For application components,
the capabilities provided by Anypoint Platform enable the following important specific features,
properties and activities:

• Backend system integration

• Fault-tolerant API invocation

© 2017 MuleSoft Inc. 26

Anypoint Platform Architecture Application Network Design

• HA and scalable execution

• Monitoring and alerting of API implementations and, if possible, API clients

Capabilities related to API clients and implementations

Backend System HA and Scalable

Integration Execution

Fault-Tolerant API Monitoring and

Invocation Alerting of API
Implementations

Figure 19. Important derived capabilities related to API clients and API implementations

2.3.4. Introducing important derived capabilities related to

APIs and API invocations
For APIs and API invocations themselves, rather than for the underlying application
components that implement or invoke these APIs, the capabilities provided by Anypoint
Platform enable the following important specific features, properties and activities:

• API design
• API policy enforcement and alerting
• Monitoring and alerting of API invocations
• Analytics and reporting of API invocations, including the reporting on meeting of SLAs
• Discoverable assets for the consumption of anyone interested in the application network,
such as API consumers and API providers
• Engaging documentation, primarily for the consumption of API consumers
• Self-service API client registration for API consumers

Capabilities related to APIs and API invocations

API Design API Policy Monitoring and

Enforcement and Alerting of API
Alerting Invocations

Analytics and Discoverable Engaging

Reporting of API Assets Documentation
Invocations

Self-Service API
Client
Registration

Figure 20. Important derived capabilities related to APIs and API invocations

© 2017 MuleSoft Inc. 27

Anypoint Platform Architecture Application Network Design

2.4. Introducing Anypoint Platform

2.4.1. Revisiting Anypoint Platform components

For resources that introduce Anypoint Platform see Course prerequisites.

What follows is a brief recap of the components of Anypoint Platform:

• Anypoint Design Center: Development tools to design and implement APIs, integrations and
connectors [Ref2]:
◦ API designer
◦ Flow designer
◦ Anypoint Studio
◦ Connector DevKit
◦ APIKit
◦ MUnit
◦ RAML SDKs
• Anypoint Management Center: Single unified web interface for Anypoint Platform
administration:
◦ Anypoint API Manager [Ref3]
◦ Anypoint Runtime Manager [Ref5]
◦ Anypoint Analytics [Ref7]
◦ Anypoint Access management [Ref6]
• Anypoint Exchange: Save and share reusable assets publicly or privately [Ref4]. Preloaded
content includes:
◦ Anypoint Connectors
◦ Anypoint Templates
◦ Examples
◦ WSDLs
◦ RAML APIs
◦ Developer Portals
• Mule runtime and Runtime services: Enterprise-grade security, scalability, reliability and
high availability:
◦ Mule runtime [Ref1]
◦ CloudHub

© 2017 MuleSoft Inc. 28

Anypoint Platform Architecture Application Network Design

◦ Anypoint MQ [Ref8]
◦ Anypoint Enterprise Security
◦ Anypoint Fabric
▪ Worker Scaleout
▪ Persistent VM Queues
◦ Anypoint Virtual Private Cloud (VPC)
• Anypoint Connectors:
◦ Connectivity to external systems
◦ Dynamic connectivity to API specifications
◦ Build custom connectors using Connector DevKit
• Hybrid cloud

Figure 21. Anypoint Platform and its main components

© 2017 MuleSoft Inc. 29

Anypoint Platform Architecture Application Network Design

Figure 22. Some of the Anypoint Connectors published in Anypoint Exchange

2.4.2. Understanding automation on Anypoint Platform

Anypoint Platform exposes a consolidated web UI for easy interaction also with users of all
levels of expertise. Screenshots in this course are from that web UI.

All functionality exposed in the web UI is also available via Anypoint Platform APIs: these are
JSON REST APIs which are also invoked by the web UI. Anypoint Platform APIs anable
extensive automation of the interaction with Anypoint Platform.

MuleSoft also provides higher-level automation tools that capitalize on the presence of
Anypoint Platform APIs:

• Anypoint CLI, a command-line interface providing a comfortable interactive layer on top of

Anypoint Platform APIs
• Mule Maven Plugin, a Maven plugin automating deployment of Mule applications (including
API implementations) to all kinds of Mule runtimes, typically used in CI/CD (see Section
9.1.2)

Related to this discussion is the observation that Anypoint Exchange is also accessible as a
Maven repository. This means that a Maven POM can be configured to deploy artifacts into
Anypoint Exchange and retrieve artifacts from Anypoint Exchange, just like with any other
Maven repository (such as Nexus).

Summary
• MuleSoft’s mission is "To connect the world’s applications, data and devices to transform

© 2017 MuleSoft Inc. 30

Anypoint Platform Architecture Application Network Design

business"
• MuleSoft proposes to close the increasing IT delivery gap through a consumption-oriented
operating model with modern APIs as the core enabler
• API-led connectivity defines tiers for Experience APIs, Process APIs and System APIs with
distinct stakeholders and focus
• An application network emerges from the repeated application of API-led connectivity and
stresses self-service, visibility, governance and security
• Anypoint Platform provides the capabilities for realizing application networks
• Anypoint Platform consists of these high-level components: Anypoint Design Center,
Anypoint Management Center, Anypoint Exchange, Mule runtime, Anypoint Connectors,
Runtime services, Hybrid cloud
• Interaction with Anypoint Platform can be extensively automated

© 2017 MuleSoft Inc. 31

Anypoint Platform Architecture Application Network Design

Chapter 3. Establishing Organizational and

Platform Foundations

Objectives
• Establish a C4E at Acme Insurance and identify KPIs to measure its success
• Understand options for hosting Anypoint Platform and provisioning Mule runtimes
• In Anypoint Platform set-up organizational structure and Identity Management for Acme
Insurance
• Contrast and compare Identity Management and Client Management on Anypoint Platform

3.1. Establishing a Center for Enablement (C4E) at

Acme Insurance

3.1.1. Assessing Acme Insurance's integration capabilities

The New Owners contract a well-known management consultancy to assess Acme Insurance’s
capabilities to embark on the strategic initiatives introduced in Acme Insurance's motivation to
change. One focus of this assessment are Acme Insurance’s IT capabilities in general and
integration capabilities in particular. The findings are:

• LoBs (personal motor and home) have a long history of independence, also in IT
• LoBs have strong IT skills, medium integration skills but no know-how in API-led
connectivity or Anypoint Platform
• Acme IT is small but enthusiastic about application networks and API-led connectivity
• DevOps capabilities are present in LoB IT and Acme IT
• Corporate IT lacks the capacity and desire to involve themselves directly in Acme
Insurance’s Enterprise Architecture. All they care about is that corporate principles are
being followed, as summarized in Figure 3

3.1.2. A decentralized C4E for Acme Insurance

Based on the above analysis of Acme Insurance’s integration capabilities and organizational
characteristics, Acme Insurance and Corporate IT agree on the establishment of a C4E at
Acme Insurance with the following guiding principles:

enable
Enables LoBs to fulfil their integration needs

© 2017 MuleSoft Inc. 32

Anypoint Platform Architecture Application Network Design

API-first
Uses API-led connectivity as the main architectural approach

asset-focused
Provides directly valuable assets rather than just documentation contributing to this goal

self-service
Assets are to be self-service consumed (initially) and (co-) created (ultimately) by the LoBs

reuse-driven
Assets are to be reused wherever applicable

federated
Follows a decentralized, federated operating model

The decentralized nature of the C4E matches well

• Acme Insurance’s division into LoBs

• the IT skills available in the LoBs
• Acme Insurance’s relationship with The New Owners

Remarks:

• The "enable" principle defines an Outcome-Based Delivery model (OBD) for the C4E
• The principles of "self-service", "reuse-driven" and "federated" promise increased
integration delivery speed
• Overall the C4E aims for a streamlined, lean engagement model, as also reflected in the
"asset-focused" principle
• This discussion omits questions of funding the C4E and whether C4E staff is fully or partially
assigned to the C4E

© 2017 MuleSoft Inc. 33

Anypoint Platform Architecture Application Network Design

The New
Owners

Acme Corporate HQ Other

Insurance HQ Acquisitions'
HQs

Personal Home LoB Acme IT Corporate IT

Motor LoB

Personal Motor Claims Motor Home Home Claims Home LoB IT C4E
Motor LoB IT Underwriting Underwriting

LoB IT Project LoB IT Project Platform API Architect DevOps

Teams Teams Architect Architect

API Architect Integration Integration API Architect Integration Integration

Architect Dev Architect Dev

Figure 23. Organizational view into Acme Insurance's target Business Architecture with a C4E
supporting LoBs and their project teams with their integration needs. C4E roles are shown in
blue

3.1.3. Exercise 1: Measuring success of the C4E

Thinking back on the application network vision on the one hand, and the principles of Acme
Insurance’s' C4E on the other hand:

1. Compile a list of statements which, if largely true, allow the conclusion that the C4E is
successful
2. Compile a similar list that allows the conclusion that the application network has grown to a
significant size
3. From the above lists, extract a list of metrics that measure success for the C4E and growth
of the application network

Solution

See Section 3.1.4.

3.1.4. Key Performance Indicators measuring the success of

Acme Insurance's C4E and the growth of its application
network
Acme Insurance uses the following key performance indicators (KPIs) to measure and track
the success of the C4E and its activities, as well as the growth and health of the application
network.

© 2017 MuleSoft Inc. 34

Anypoint Platform Architecture Application Network Design

All of the metrics can be extracted automatically, through REST APIs, from Anypoint Platform.

• # of assets published to Anypoint Exchange

• # of interactions with Anypoint Exchange assets
• # of APIs managed by Anypoint Platform
• # of System APIs managed by Anypoint Platform
• # of API clients registered for access to APIs
• # of API implementations deployed to Anypoint Platform
• # of API invocations
• # or fraction of lines of code covered by automated tests in CI/CD pipeline
• Ratio of info/warning/critical alerts to number of API invocations

Figure 24. Number of assets published to Anypoint Exchange over time

Figure 25. Current number of assets published to Anypoint Exchange grouped by type of asset

© 2017 MuleSoft Inc. 35

Anypoint Platform Architecture Application Network Design

3.2. Understanding Anypoint Platform deployment

scenarios

3.2.1. Introducing MuleSoft-hosted and customer-hosted

Anypoint Platform deployments
See [Ref5], [Ref9], [Ref10].

Figure 26. Overview of Anypoint Platform deployment options and MuleSoft product names (in
bold) for each supported scenario. The Anypoint Platform management plane comprises
Anypoint API Manager and Anypoint Runtime Manager

Options for the deployment of the management plane of Anypoint Platform, i.e., Anypoint API
Manager and Anypoint Runtime Manager:

• MuleSoft-hosted:
◦ Product: Anypoint Platform
• Customer-hosted:
◦ Product: Anypoint Platform Private Cloud Edition

Options for the deployment and provisioning of Mule runtimes:

• MuleSoft-managed:
◦ In the public Amazon Web Services cloud: CloudHub
◦ In an Amazon Web Services VPC: CloudHub with Anypoint VPC
• Customer-managed:
◦ On-premises, manually provisioned
◦ In a customer-managed cloud:

© 2017 MuleSoft Inc. 36

Anypoint Platform Architecture Application Network Design

▪ On Pivotal Cloud Foundry: Anypoint Platform for Pivotal Cloud Foundry

▪ On OpenShift (community-driven, not productized)

Options for the PaaS functionality of Anypoint Platform, i.e., the execution of Mule applications
by automatically provisioned Mule runtimes:

• MuleSoft-managed:
◦ Product: CloudHub, which is a part of the MuleSoft-hosted Anypoint Platform
• Customer-managed:
◦ Product: Anypoint Platform for Pivotal Cloud Foundry
◦ Anypoint Platform Private Cloud Edition with community-driven PaaS elements for
OpenShift

3.2.2. MuleSoft-hosted Anypoint Platform and Mule runtimes

via PaaS in public cloud

Figure 27. MuleSoft-hosted Anypoint Platform managing MuleSoft-managed PaaS-provisioned

Mule runtimes on CloudHub in the public cloud

3.2.3. MuleSoft-hosted Anypoint Platform and Mule runtimes

via PaaS in Amazon Web Services VPC

© 2017 MuleSoft Inc. 37

Anypoint Platform Architecture Application Network Design

Figure 28. MuleSoft-hosted Anypoint Platform managing MuleSoft-managed PaaS-provisioned

Mule runtimes on CloudHub in an Amazon Web Services VPC

3.2.4. MuleSoft-hosted Anypoint Platform and customer-

managed Mule runtimes

© 2017 MuleSoft Inc. 38

Anypoint Platform Architecture Application Network Design

Figure 29. MuleSoft-hosted Anypoint Platform managing customer-managed Mule runtimes,

such as on-premises Mule runtimes

3.2.5. Customer-hosted Anypoint Platform and Mule runtimes

Figure 30. Customer-hosted Anypoint Platform Private Cloud Edition managing customer-
managed Mule runtimes, such as on-premises Mule runtimes

© 2017 MuleSoft Inc. 39

Anypoint Platform Architecture Application Network Design

3.2.6. Customer-hosted Anypoint Platform and Mule runtimes

via PaaS on Pivotal Cloud Foundry

Figure 31. Customer-hosted Anypoint Platform for Pivotal Cloud Foundry managing customer-
managed PaaS-provisioned Mule runtimes on PCF

© 2017 MuleSoft Inc. 40

Anypoint Platform Architecture Application Network Design

Figure 32. Customer-hosted Anypoint Platform for Pivotal Cloud Foundry managing customer-
managed PaaS-provisioned Mule runtimes on PCF, where the Mule runtimes only host API
proxies infront of API implementations that are not Mule applications

3.2.7. Anypoint Platform differences between deployment

scenarios
Anypoint Platform deployment options differ in various ways:

• At the highest level, not all Anypoint Platform components are currently available for every
Anypoint Platform deployment scenario.
• Some features of Anypoint Platform components that are available in more than one
deployment scenario differ in their details, typically due to the different technical
characteristics and capabilities available in each case.

Table 1. Availability of Anypoint Platform components and high-level features in different

deployment scenarios.
Component, MuleSoft-hosted Hybrid Anypoint Anypoint
Feature Anypoint Platform Private Platform for
Platform Cloud Edition Pivotal Cloud
Foundry
API designer yes yes yes yes
Flow designer yes yes no no
Anypoint Access yes yes yes yes
management

© 2017 MuleSoft Inc. 41

Anypoint Platform Architecture Application Network Design

Component, MuleSoft-hosted Hybrid Anypoint Anypoint

Feature Anypoint Platform Private Platform for
Platform Cloud Edition Pivotal Cloud
Foundry
LDAP for Identity no no yes yes
Management
Anypoint yes yes yes yes
Runtime
Manager
External Runtime no yes yes yes
Analytics
Schedules UI yes no no no
Anypoint Runtime yes yes no no
Manager
monitoring
dashboards
Insight yes yes no no
Anypoint Runtime yes yes no no
Manager alerts
Anypoint API yes yes yes yes
Manager
Anypoint API yes yes no no
Manager alerts
Anypoint yes yes no no
Analytics
External API no yes yes yes
Analytics
Anypoint yes yes yes yes
Exchange
Anypoint MQ yes yes no no
PaaS yes (CloudHub) no no yes
Mule runtime load yes (Fabric) no no yes (PCF)
balancing
Mule runtime yes (Fabric) yes yes yes
persistent VM
queues
Mule runtime yes no no yes
auto-restart
Mule runtime no yes yes yes
cluster
Zero downtime yes no no yes
deployments

Notes:

• External Analytics refers to Splunk, ELK or similar software

• Persistent VM queues in a non-CloudHub deployment scenario have many more options,
such as cluster-wide in-memory replication or persistence on disk or in a database, but may

© 2017 MuleSoft Inc. 42

Anypoint Platform Architecture Application Network Design

require management of persistent storage

• The Tanuki Software Java Service Wrapper offers limited auto-restart capabilities also for
customer-managed Mule runtimes, but this is not comparable to CloudHub’s or PCF’s
health-check-based auto-restart feature
• Anypoint Runtime Manager alerts on CloudHub (and only on CloudHub) also include the
option of custom alerts and notifications (via the CloudHub connector)
• Anypoint Platform Private Cloud Edition supports minimal Anypoint Runtime Manager alerts
related to the Mule application being deployed, undeployed, etc., but no alerts based on
Mule events or API events
• Anypoint Runtime Manager monitoring dashboards include load and performance metrics
for Mule applications and the servers to which Mule runtimes are deployed
• Insight is a troubleshooting tool that gives in-depth visibility into Mule applications by
collecting Mule events (business events and default events) and the transactions to which
these events belong. Only CloudHub supports the replay of transactions (which causes re-
processing the involved message)
• Clustering Mule runtimes when deploying through Anypoint Platform for Pivotal Cloud
Foundry requires a PCF Hazelcast service. Mule runtime clusters in Hybrid and Anypoint
Platform Private Cloud Edition deployment scenarios only need and use the Hazelcast
features built into the Mule runtime itself.

3.2.8. Exercise 2: Pros and cons of various deployment

scenarios
Reflecting on the various deployment scenarios supported by Anypoint Platform:

1. Discuss the advantages and disadvantages of each scenarios.

2. What requirements would clearly require one particular deployment scenario?
3. Which deployment scenario minimizes time-to-market?

Solution

Anypoint Platform deployment scenarios can be evaluated along the following dimensions:

• Regulatory or IT operations requirements that mandate on-premises processing of every

data item, including meta-data about API invocations and messages processed within Mule
applications: requires Anypoint Platform Private Cloud Edition or Anypoint Platform for
Pivotal Cloud Foundry
• Time-to-market, assuming the effort to deploy Anypoint Platform must be included in the
elapsed time: favors MuleSoft-hosted Anypoint Platform

© 2017 MuleSoft Inc. 43

Anypoint Platform Architecture Application Network Design

• IT operations effort: favors MuleSoft-hosted Anypoint Platform over all other deployment
scenarios; favors Anypoint Platform for Pivotal Cloud Foundry over Anypoint Platform
Private Cloud Edition
• Latency and throughput when accessing on-premises data sources: favors scenarios where
Mule runtimes can be deployed close to these data sources, i.e., Anypoint Platform Private
Cloud Edition and Anypoint Platform for Pivotal Cloud Foundry
• Control over Mule runtime characteristics like JVM and machine memory, garbage collection
settings, hardware, etc.: favors Hybrid and Anypoint Platform Private Cloud Edition over
Anypoint Platform for Pivotal Cloud Foundry over MuleSoft-hosted Anypoint Platform

3.3. Onboarding Acme Insurance onto Anypoint

Platform

3.3.1. Anypoint Access management

• Controls access to entitlement areas in Anypoint Platform
• Manage
◦ Business groups, users, roles and permissions
◦ Environments
◦ Other Resources

Figure 33. Anypoint Access management and the Anypoint Platform entitlements

© 2017 MuleSoft Inc. 44

Anypoint Platform Architecture Application Network Design

Figure 34. Anypoint Access management controls access to and allocation of various resources
on Anypoint Platform

3.3.2. Anypoint Platform organizations and business groups

• Organization: An administrative collection of resources and users
• Business group: A sub-organization at any level

Figure 35. Anypoint Access management at the level of the Personal Motor LoB business group

3.3.3. Identity Management vs Client Management in Anypoint

Platform
• Identity Management is concerned with users of Anypoint Platform
◦ includes users of the Anypoint Platform web UI and the Anypoint Platform APIs

© 2017 MuleSoft Inc. 45

Anypoint Platform Architecture Application Network Design

◦ enables Single Sign-On (SSO)

• Client Management is concerned with API clients using OAuth 2.0

By default, Anypoint Platform acts as an Identity Provider for Identity Management. But
Anypoint Platform also supports configuring one external Identity Provider for each of these
two uses, independently of each other.

If an external Identity Provider is configured for Identity Management, then this is currently
used only for interactions with the Anypoint Platform web UI and not for invocations of the
Anypoint Platform APIs. Therefore, before configuring an external Identity Provider for Identity
Management, setup administrative users for invoking the Anypoint Platform APIs. These will
remain valid after the external Identity Provider has been configured.

3.3.4. Supported Identity Provider standards and products

For Identity Management Anypoint Platform supports:

• The mapping of Anypoint Platform roles to groups in an external Identity Provider

• OpenID Connect
◦ a standard implemented by Identity Providers such as PingFederate, OpenAM, Okta
◦ does not support single log-out
• SAML 2.0
◦ a standard implemented by Identity Providers such as PingFederate, OpenAM, Okta,
Shibboleth, Active Directory Federation Services (AD FS), onelogin, CA Single Sign-On
◦ supports single log-out
• LDAP
◦ a standard that is supported for Identity Management only on Anypoint Platform Private
Cloud Edition

For Client Management Anypoint Platform supports the following Identity Providers as OAuth
2.0 servers:

• OpenAM
• PingFederate

3.3.5. Selecting an Identity Provider for Acme Insurance

Acme Insurance currently uses Microsoft Active Directory (AD) to store user accounts.

After a brief evaluation period Acme Insurance chooses PingFederate as an Identity Provider

© 2017 MuleSoft Inc. 46

Anypoint Platform Architecture Application Network Design

ontop of AD. They configure their Anypoint Platform organization in the MuleSoft-hosted
Anypoint Platform to access their on-premises PingFederate instance for Identity Management.

Acme Insurance is currently unsure whether they will need OAuth 2.0, but if they do, they plan
to use the same PingFederate instance also for Client Management.

Summary
• A federated C4E is established to facilitate API-led connectivity and the growth of an
application network
◦ Federation plays to the strength of Acme Insurance’s LoB IT
◦ KPIs to measure the C4E’s success are defined and monitored
• Anypoint Platform can be hosted by MuleSoft or customers
• Mule runtimes used with Anypoint Platform can be provisioned manually or through a PaaS
• PaaS-provisioning of Mule runtimes is supported via CloudHub or Anypoint Platform for
Pivotal Cloud Foundry
• Not all Anypoint Platform components are available in all deployment scenarios
• Acme Insurance and its LoBs and users are onboarded onto Anypoint Platform using an
external Identity Provider
• Identity Management and Client Management are clearly distinct functional areas, both
supported by Identity Providers

© 2017 MuleSoft Inc. 47

Anypoint Platform Architecture Application Network Design

Chapter 4. Identifying, Reusing and Publishing

APIs

Objectives
• Map Acme Insurance’s planned strategic initiatives to products and projects
• Identify APIs needed to implement these products
• Assign each API to one of the three tiers of API-led connectivity
• Understand in detail composition and collaboration of APIs
• Reuse APIs wherever possible
• Publish APIs and related assets for reuse

4.1. Productizing Acme Insurance's strategic initiatives

4.1.1. Translating strategic initiatives into products, projects

and features
Acme Insurance has committed to realize the two most pressing strategic initiatives introduced
ealier (see Acme Insurance's motivation to change):

• Open-up to Aggregators for motor insurance

• Provide self-service capabilities to customers

All relevant stakeholders come together to concretize these strategic initiatives into two
minimally viable products and their defining features:

• The "Aggregator Integration" product

◦ with the "Create quote for aggregators" feature as the defining feature
• The "Customer Self-Service App" product
◦ with the "Retrieve policy holder summary" feature as one defining feature
◦ and the "Submit auto claim" feature as the other defining feature

The products' features realize the requirements defined by the strategic initiatives.

© 2017 MuleSoft Inc. 48

Anypoint Platform Architecture Application Network Design

Open to Provide Self-

Aggregators Service
Capabilities

Create quote for Retrieve policy Submit auto claim

aggregators holder summary

Aggregator Customer Self-

Integration Service App

Figure 36. Architecturally significant features of the immediately relevant strategic initiatives,
and the products they are assigned to

The two products "Aggregator Integration" product and "Customer Self-Service App" product
are assigned to two project teams. The project for the "Aggregator Integration" product is
kicked-off immediately, while the project for the "Customer Self-Service App" product starts
with some delay.

This project for the "Aggregator Integration" product is the first to use API-led connectivity at
Acme Insurance, and is also the one etablishing the foundation of what will become the Acme
Insurance application network.

4.2. Identifying APIs for the "Aggregator Integration"

product

4.2.1. Towards an application network

The "Aggregator Integration" product is Acme Insurance’s immediate priority. It has just one
defining feature, the "Create quote for aggregators" feature (see Figure 36).

The project to implement the "Aggregator Integration" product kicks off at the Personal Motor
LoB, and is actively supported by the newly established C4E within Acme IT.

This is the first API-led connectivity project at Acme Insurance, so it must establish an
Enterprise Architecture compatible with an application network. The resulting application
network will at first be minimal, just enough to sustain the "Aggregator Integration" product,
but it will grow subsequently when the "Customer Self-Service App" product is realized.

Within the application network and API-led connectivity frameworks, you first architect for the
functional and later, in Section 5.1, for the non-functional requirements of this feature.

© 2017 MuleSoft Inc. 49

Anypoint Platform Architecture Application Network Design

4.2.2. "Create quote for aggregators" feature business process

view
Analyzing the "Create quote for aggregators" feature, you observe that it can be realized by
one end-to-end business process, the "Create Aggregator Quotes" business process:

1. The business process is triggered by the receipt of a policy description from the Aggregator
2. First it must be established whether the policy holder for whom the quote is to be created is
an existing customer of Acme Insurance, i.e., whether they already hold a policy at Acme
Insurance
3. Applicable policy options (collision coverage, liability coverage, comprehensive insurance, …
) must be retrieved based on the policy description
4. Policy options must be ranked such that options must likely to be attractive to the customer
and most lucrative to Acme Insurance appear first
5. One policy quote must be created for each of the top-5 policy options
6. The business process ends with the delivery (return) of the top-5 quotes to the Aggregator

Create Aggregator Quotes

Aggregator Search Policy Retrieve Rank Policy Create Quotes

Policy Holder Available Options Quotes for Delivered to
Description Policy Top Policy Aggregator
Received Options Options

Figure 37. High-level view of the "Create Aggregator Quotes" business process

4.2.3. Looking ahead to the NFRs for the "Create quote for
aggregators" feature
To give a bit more context for the following discussion, it is helpful to briefly inspect the non-
functional requirements (NFRs) that will have to be fulfilled for the "Create quote for
aggregators" feature: see Section 5.1.1.

4.2.4. Exercise 3: Identify APIs for the "Create quote for

aggregators" feature in all tiers
Using the "Create Aggregator Quotes" business process and knowledge of the capabilities of
the Policy Admin System, break down the required functionality of the "Create quote for
aggregators" feature into APIs in the 3 tiers of API-led connectivity:

• Experience APIs are defined by the Aggregator as the "user-visible app"

© 2017 MuleSoft Inc. 50

Anypoint Platform Architecture Application Network Design

◦ Custom-designed for a specific user interaction

◦ May change comparatively often as user-visible apps change often
• Process APIs implement and orchestrate pure business/process logic
◦ Serve Experience APIs but are independent of the concrete top-level API clients that
determine the Experience APIs
• System APIs are defined by the needs of the Process APIs and the capabilities of the Policy
Admin System
◦ Typically many System APIs in-front of the same backend system
◦ Change comparatively rarely as backend systems change rarely

Solution

Aggregator Create quote for

aggregators

Aggregator
Quote Creation

Experience APIs

Aggregator
Quote Creation
API

create
Process APIs

Policy Holder Policy Options Motor Quote API

Search API Ranking API

System APIs

Motor Policy Home Policy Policy Options Motor Quote Motor Quote
Holder Search Holder Search Retrieval API Creation New Creation Addon
API API Business API Business API

Policy Admin
System

Figure 38. Experience API, Process APIs and System APIs collaborating for the "Create quote
for aggregators" feature and ultimately serving the needs of the Aggregator

You observe that the "Create quote for aggregators" feature can be implemented by one
synchronous invocation of the "Aggregator Quote Creation Experience API" which in turn
triggers synchronous invocations of several APIs in all 3 tiers of the architecture, ultimately
leading to multiple invocations of the Policy Admin System.

This serves the functional requirements of this feature, but will need to be revisited when NFRs

© 2017 MuleSoft Inc. 51

Anypoint Platform Architecture Application Network Design

are discussed.

Summary

• Essential aspect of "Create quote for aggregators" feature implemented by one

synchronous invocation of the "Aggregator Quote Creation Experience API"
• In turn triggers synchronous invocations of several APIs in all 3 tiers of the architecture
• Ultimately leads to invocations of the Policy Admin System

4.2.5. Details of the "Aggregator Quote Creation Experience

API"
To be explicit about some of the components of the "Aggregator Quote Creation Experience
API":

• The technology interface of the "Aggregator Quote Creation Experience API" is an

XML/HTTP API that is invoked by the Aggregator
• The API implementation of the "Aggregator Quote Creation Experience API" invokes various
Process APIs, such as the "Policy Holder Search Process API"

© 2017 MuleSoft Inc. 52

Anypoint Platform Architecture Application Network Design

Aggregator Quote Creation API

Aggregator
Quote Creation

Aggregator Aggregator
Quote Creation Quote Creation
Service API

Aggregator Quote Aggregator

Creation Quote Creation
Implementation XML/HTTP API

Policy Holder Aggregator

Search JSON
REST API

Policy Options
Ranking JSON
REST API

Create Motor
Quote JSON REST
API

Figure 39. "Aggregator Quote Creation Experience API", serving the Aggregator

4.2.6. Details of the "Policy Holder Search Process API"

"Policy Holder Search Process API" is a Process API with the following important
characteristics:

• Its technology interface is a JSON REST API that is invoked by the API implementation of
the "Aggregator Quote Creation Experience API"
• Its API implementation invokes two System APIs, one of them being the "Motor Policy
Holder Search System API"

© 2017 MuleSoft Inc. 53

Anypoint Platform Architecture Application Network Design

Policy Holder Search API

Policy Holder
Search

Policy Holder Policy Holder

Search Service Search API

Policy Holder Policy Holder

Search Search JSON
Implementation REST API

Motor Policy Aggregator Quote

Holder Search Creation
JSON REST API Implementation

Home Policy
Holder Search
JSON REST API

Figure 40. "Policy Holder Search Process API", initially serving the API implementation of the
"Aggregator Quote Creation Experience API"

4.2.7. Details of the "Motor Policy Holder Search System API"

"Motor Policy Holder Search System API" is a System API with the following important
characteristics:

• Its technology interface is a JSON REST API that is invoked by the API implementation of
the "Policy Holder Search Process API"
• Its API implementation invokes the Policy Admin System over an unidentified technology
interface (MQ-based, see Section 7.1.3)

© 2017 MuleSoft Inc. 54

Anypoint Platform Architecture Application Network Design

Motor Policy Holder Search API

Motor Policy
Holder Search

Motor Policy Motor Policy

Holder Search Holder Search
Service API

Motor Policy Holder Motor Policy

Search Holder Search
Implementation JSON REST API

Policy Admin Policy Holder

System Search
Implementation

Figure 41. "Motor Policy Holder Search System API", exposing existing functionality in the
Policy Admin System, and initially serving the API implementation of the "Policy Holder Search
Process API"

4.2.8. API-business alignment

You confirm that this proposal for the APIs realizing the "Create quote for aggregators" feature
is aligned with the "Create Aggregator Quotes" business process.

© 2017 MuleSoft Inc. 55

Anypoint Platform Architecture Application Network Design

Create Aggregator Quotes

Aggregator Search Policy Retrieve Rank Policy Create Quotes

Policy Holder Available Options Quotes for Delivered to
Description Policy Top Policy Aggregator
Received Options Options

Aggregator
Quote
Creation API

Policy Holder Policy Motor Quote

Search API Options API
Ranking API

Policy
Options
Retrieval API

Figure 42. How APIs in all tiers serve the "Create Aggregator Quotes" business process

4.2.9. Exercise 4: Improve reusability of "Create quote for

aggregators" feature APIs
As you better understand the "Create quote for aggregators" feature, you discover that other
Aggregators use different data formats for communicating with insurance providers:

1. Analyze the APIs identified for the realization of the "Create quote for aggregators" feature
with respect to their dependency on the data format exchanged with the Aggregator
2. Identify new APIs and refine existing APIs to maximize reuse when other Aggregators will
need to be supported in the future
3. Describe as clearly as possible which elements of the currently identified APIs will have to
change to accommodate your proposed changes

Solution

• Only the "Aggregator Quote Creation Experience API" depends on the Aggregator-defined
data format
• In the future there will be one Experience API per Aggregator, similar to "Aggregator Quote
Creation Experience API"
• The common functionality of these Experience APIs should be encapsulated in a new
Process API, e.g. the "One-Step Motor Quote Creation Process API"
◦ Accepts and returns Aggregator-neutral description of policy and quotes
• Changes:

© 2017 MuleSoft Inc. 56

Anypoint Platform Architecture Application Network Design

◦ "Aggregator Quote Creation Experience API": Interface unchanged, implementation

changed significantly to mainly delegate to "One-Step" Process API
◦ New "One-Step" Process API with implementation similar to the orchestration logic in the
current "Aggregator Quote Creation Experience API"
◦ New Experience APIs, one per Aggregator, delegating to "One-Step" Process API
◦ Other APIs remain unchanged

This scenario, i.e., the refactoring of an existing Experience API to adapt to an improved
understanding of an integration scenario, is a concrete realization of the claim that application
networks are recomposable and "bend but don’t break" under change (see Section 2.2.13).
The current Aggregator as an existing client of the "Aggregator Quote Creation Experience
API" does not experience any change as the "Aggregator Quote Creation Experience API" API
implementation is refactored to use the new "One-Step" Process API. At the same time,
technical debt for the existing, misguided implementation of the "Aggregator Quote Creation
Experience API" is paid back immediately by the creation of the new "One-Step" Process API
and the re-use of the orhcestration logic hidden in "Aggregator Quote Creation Experience
API".

4.3. Reusing and publishing API-related assets for the

"Aggregator Integration" product

4.3.1. Steps to reusing API-related assets

You have identified APIs that will need to be designed and implemented in later stages of the
project. But maybe someone in the organization has already provided these or sufficiently
similar APIs? You check for this possibility by searching Anypoint Exchange.

As the application network is just being established, Anypoint Exchange currently contains no
APIs that can be reused for this feature. In order to announce the fact that the chosen APIs
will be implemented, you immediately create an API Portal for each API and link it to Acme
Insurance’s Developer Portal and Anypoint Exchange. In order to create these assets, a basic
API specification, preferably in the form of a RAML definition, is required for the API.

The C4E provides guidance and support with these activities. Importantly, the C4E defines
naming conventions for all assets, including for those to be published in Anypoint Exchange_.

4.3.2. Defining RAML

See the corresponding glossary entry.

© 2017 MuleSoft Inc. 57

Anypoint Platform Architecture Application Network Design

4.3.3. "Policy Holder Search Process API" documentation

API documentation and assets need to be created for all APIs identified so far. The discussion
here picks the "Policy Holder Search Process API" as an example.

API documentation for the "Policy Holder Search Process API" is a form of contract for all
elements of the API, i.e., its business service, application service, application interface and
technology interface. The RAML definition of the API is the most important way of expressing
that contract.

API documentation must be discoverable and engaging for it to be effective: two capabilities
that are provided by Anypoint Platform as discussed shortly.

You document various aspects of the API as follows:

• Details of the JSON/REST interface to the API should be exhaustively specified in the RAML
definition of the API
• The same is true for security constraints like required HTTPS protocol and authentication
mechanisms
◦ Currently unknown information can be added later to the RAML definition, for instance
when NFRs are addressed
• Other NFRs, like throughput goals are not part of the RAML definition but the wider API
documentation, specifically the API Portal

© 2017 MuleSoft Inc. 58

Anypoint Platform Architecture Application Network Design

Policy Holder Search API

Policy Holder Engaging

Policy Holder Search
Search Documentation
API Documentation

Discoverable
Assets

Policy Holder Policy Holder Throughput goal

Search Service Search API / constraint

HTTPS and auth

security
constraints
Policy Holder Policy Holder Policy Holder Search JSON REST
Search Search JSON RAML Definition interface
Implementation REST API definitions

Aggregator Quote API Consumer

Creation
Implementation

Figure 43. Documentation for the "Policy Holder Search Process API", including its RAML
definition, documents the business service realized by the API, its SLA and non-functional
aspects. API documentation must also be discoverable and engaging, as it must be easy to
access by API consumers

4.3.4. Using API designer to sketch and simulate a RAML

definition for "Policy Holder Search Process API"
Using API designer, a feature of Anypoint Design Center, you sketch a first draft of the API
specification of "Policy Holder Search Process API" in the form of a RAML definition such that

• its purpose and

• the essential elements of its interface
◦ name, version and description of API
◦ preliminary resources and methods

can be communicated widely within the application network.

The RAML definition is currently more of a stub, but will be amended as the project
progresses.

Using the mocking feature of API designer you confirm that the interaction with the API is
sound from the API client’s perspective.

© 2017 MuleSoft Inc. 59

Anypoint Platform Architecture Application Network Design

Figure 44. Using API designer to sketch and try-out (mock) "Policy Holder Search Process API"

4.3.5. Creating engaging documentation for "Policy Holder

Search Process API"
Anypoint Platform provides three main features for making documentation engaging: API
Portals, API Notebooks and API Consoles. These primarily serve API consumers, i.e. the users
of the API.

© 2017 MuleSoft Inc. 60

Anypoint Platform Architecture Application Network Design

Engaging
Documentation

API Portal

Policy Holder Search

API Portal

Policy Holder Search

API Documentation

API Notebook
API
Policy Holder Search Consumer
API Notebooks

Policy Holder Search

RAML Definition

API Console

Policy Holder Search

API Console

Figure 45. Creating an API Portal with API Notebook and an API Console for the "Policy Holder
Search Process API" makes for engaging API documentation serving API consumers

4.3.6. Creating an API Portal for "Policy Holder Search Process

API"
Every API in the application network must be documented with an API Portal, which is,
together with the Anypoint Exchange asset, the main entry point to the documentation for that
API. Apart from textual or multi-media documentation of the API, the API Portal should contain
an API Notebook and an API Console.

At this early stage in the project you should already create an API Portal for the "Policy Holder
Search Process API" which should at the very least document what cannot be expressed in the
RAML definition:

• E.g., HTTPS mutual authentication for the "Aggregator Quote Creation Experience API"
(which is a different API)

© 2017 MuleSoft Inc. 61

Anypoint Platform Architecture Application Network Design

Figure 46. Creating an API Portal for "Policy Holder Search Process API"

4.3.7. Including an API Console for "Policy Holder Search

Process API"
Anypoint Platform can fully automatically create a web UI to trigger API invocations of an API
with a RAML definition. This feature is available

• when designing an API in API designer

• for inclusion in the API Portal for an API, where it is called "API reference"
• when implementing the API in Anypoint Studio

Include an API Console for the "Policy Holder Search Process API" into its API Portal, using the
preliminary RAML definition created earlier.

© 2017 MuleSoft Inc. 62

Anypoint Platform Architecture Application Network Design

Figure 47. Including an API Console in the API Portal for "Policy Holder Search Process API"

4.3.8. Including an API Notebook for "Policy Holder Search

Process API"
The API Notebook for an API makes use of the RAML definition for that API and provides an
interactive JavaScript-based coding environment that can be used to document interactions
with the API. You create an API Notebook for the "Policy Holder Search Process API" to
demonstrate how to invoke the features it provides.

Include an API Notebook for the "Policy Holder Search Process API" in its API Portal. This API
Notebook makes use of the API’s preliminary RAML definition created earlier.

© 2017 MuleSoft Inc. 63

Anypoint Platform Architecture Application Network Design

Figure 48. Creating an API Notebook for "Policy Holder Search Process API"

4.3.9. Making "Policy Holder Search Process API" assets

discoverable
Now that you have created an API Portal for the "Policy Holder Search Process API", this
important asset must be made discoverable within Acme Insurance:

• The API Portal for "Policy Holder Search Process API" is automatically included in Acme
Insurance’s Developer Portal
• You create an entry in Acme Insurance’s Anypoint Exchange pointing to the API Portal and
RAML definition of the "Policy Holder Search Process API"

© 2017 MuleSoft Inc. 64

Anypoint Platform Architecture Application Network Design

Discoverable
Assets

Policy Holder Search Acme Insurance Dev Portal

API Documentation
Policy Holder Search
API Portal

API
Consumer
Acme Insurance Exchange

Policy Holder Search Policy Holder Search

RAML Definition API Exchange Entry

Figure 49. Including the API Portal for the "Policy Holder Search Process API" into Acme
Insurance's Developer Portal and Anypoint Exchange makes that API documentation
discoverable by API client developers

4.3.10. Including the API Portal for "Policy Holder Search

Process API" in Acme Insurance's Developer Portal
The newly created API Portal for "Policy Holder Search Process API" is automatically included in
Acme Insurance’s Developer Portal. If this is Acme Insurance’s first API Portal, then a
Developer Portal will be created automatically by Anypoint Platform.

© 2017 MuleSoft Inc. 65

Anypoint Platform Architecture Application Network Design

Figure 50. Acme Insurance's Developer Portal showing some of the APIs available in Acme
Insurance's application network

© 2017 MuleSoft Inc. 66

Anypoint Platform Architecture Application Network Design

Figure 51. The API consumer's view of the API Portal for "Policy Holder Search Process API" is
reachable from the Acme Insurance's Developer Portal

4.3.11. Publishing an Anypoint Exchange entry for "Policy

Holder Search Process API"
Anypoint Exchange is a kind of Content-Management System specifically optimized for
supporting application networks. Anypoint Exchange can store most kinds of assets, including
references to APIs, their API Portals and RAML definitions.

Create an entry in Anypoint Exchange that references the newly created API Portal for the
"Policy Holder Search Process API" and also points to the RAML definition for that API. This
makes it even easier for API client developers to discover and reuse the API.

Strictly speaking, an Anypoint Exchange entry of type "REST API" is for a RAML definition.
Hence an Anypoint Exchange entry of type "REST API" does not represent the managed API
version, or an API endpoint or an API implementation. The version of the Anypoint Exchange
entry is therefore the artifact version of that RAML definition. Every change to the content of
that RAML definition triggers a version increase in the corresponding Anypoint Exchange entry.
This behavior is consistent with the fact that Anypoint Exchange is also a Maven-compatible
artifact repository - storing, in this case, a RAML definition. See Section 6.2 for a discussion of
versioning API-related artifacts.

© 2017 MuleSoft Inc. 67

Anypoint Platform Architecture Application Network Design

Figure 52. The Anypoint Exchange entry for "Policy Holder Search Process API", giving access
to various assets of this and previous versions of this API, such as its RAML definition, a Mule
runtime connector/plugin to invoke this API from Mule applications, the API Portal and API
endpoint URLs

"Policy Holder Search Process API" can now be discovered by two main mechanisms:

• in Acme Insurance’s Developer Portal, when browsing or searching for APIs

• in Acme Insurance’s Anypoint Exchange, when browsing or searching for any kind of asset,
including APIs

4.3.12. Repeat for all APIs for the "Create quote for
aggregators" feature
Create rudimentary RAML definitions, API Portals with API Notebooks and API Consoles, and
Anypoint Exchange entries for all APIs needed for the "Create quote for aggregators" feature.

© 2017 MuleSoft Inc. 68

Anypoint Platform Architecture Application Network Design

See Figure 50.

Figure 53. Acme Insurance's Anypoint Exchange showing some of the APIs available in Acme
Insurance's application network

4.4. Identifying, reusing and publishing APIs and API-

related assets for the "Customer Self-Service App"
product

4.4.1. Growing the application network for the "Customer Self-

Service App" product
The "Customer Self-Service App" product (which is defined as a minimally viable product) has
just two defining features, the "Retrieve policy holder summary" feature and the "Submit auto
claim" feature (see Figure 36).

This is the second API-led connectivity project at Acme Insurance, so it can already build on an
Enterprise Architecture compatible with a nascent application network.

The project team realizing the "Customer Self-Service App" product is again located at the
Personal Motor LoB. However, it is assumed that the "Retrieve policy holder summary" feature
will require access to information typically handled by the Home LoB. This product therefore
has a wider business scope than the very focused "Aggregator Integration" product addressed

© 2017 MuleSoft Inc. 69

Anypoint Platform Architecture Application Network Design

earlier. The contribution of the C4E, as a cross-LoB, Acme Insurance-wide entity, is therefore
particularly important. The federated nature of the Acme Insurance C4E should come as an
advantage here, because it means that there are C4E-aligned and -assigned roles in both
Personal Motor LoB IT and Home LoB IT.

Within the application network and API-led connectivity frameworks, you first architect for the
functional and then for the non-functional requirements of the two features of the "Customer
Self-Service App" product, in turn.

4.4.2. APIs for the "Retrieve policy holder summary" feature in

all tiers
The "Retrieve policy holder summary" feature is the first feature of the "Customer Self-Service
App" product to be analyzed. It is, however, the second API-led connectivity project in Acme
Insurance and therefore can build on a foundation of reusable assets.

You analyze the "Retrieve policy holder summary" feature, trying to break it down into APIs in
the three tiers of API-led connectivity, checking against Acme Insurance’s Anypoint Exchange
and Developer Portal as you do so:

• You discover the existing "Policy Holder Search Process API" and decide that it fits the first
step in the "Retrieve policy holder summary" feature, so you reuse it from the new "Policy
Holder Summary Process API"
• You define the new "Policy Search Process API" to support searching for policies across lines
of business (motor and home)
• The "Claims Process API" currently only needs to support searching for claims across LoBs,
but is envisioned to ultimately grow to support other operations on claims

© 2017 MuleSoft Inc. 70

Anypoint Platform Architecture Application Network Design

Customer Self- Retrieve policy

Service Mobile holder summary
App

Experience APIs

Mobile Policy
Holder Summary
API

Process APIs

Policy Holder
Summary API

search

Policy Holder Policy Search API Claims API

Search API

System APIs

Motor Policy Home Policy Motor Policy Home Policy Motor Claims Home Claims
Holder Search Holder Search Search API Search API Search API Search API
API API

Policy Admin
Motor Claims Home Claims
System
System System

Figure 54. Experience API, Process APIs and System APIs collaborating for the "Retrieve policy
holder summary" feature of the "Customer Self-Service App" product

4.4.3. APIs for the "Submit auto claim" feature in all tiers
In addition to a "Motor Claims Submission System API" you also define the "Motor Claims
Submission Process API", to insulate the Experience API from the System API. This is because

• it is very possible that the Process API will have to perform as-yet undiscovered
coordination in order to invoke the System API
• the Process API will likely need to validate the claim submission before passing it on to the
System API

© 2017 MuleSoft Inc. 71

Anypoint Platform Architecture Application Network Design

Customer Self- Submit auto claim

Service Mobile
App

Experience APIs

Mobile Auto
Claim
Submission API

Process APIs

Motor Claims
Submission API

System APIs

Motor Claims
Submission API

Motor Claims
System

Figure 55. Experience API, Process APIs and System APIs collaborating for the "Submit auto
claim" feature of the "Customer Self-Service App" product

Note that the asynchronicity of the interaction (see Section 5.2.3) is not visible in this
diagram.

4.4.4. Publishing API-related assets for the "Customer Self-

Service App" product
At this point Acme Insurance’s application network has been populated with assets for all APIs
needed for the "Aggregator Integration" product and "Customer Self-Service App" product:

• The RAML definitions for the APIs capture the important functional aspects in a preliminary
fashion

© 2017 MuleSoft Inc. 72

Anypoint Platform Architecture Application Network Design

• An API Portal has been created for each API, including an API Console and a rudimentary
API Notebook for that API
• An entry in Acme Insurance’s Anypoint Exchange has been created for each API,
referencing the API’s RAML definition and pointing to its API Portal and API endpoints
• The Acme Insurance Developer Portal gives API consumers access to all API Portals
• No NFRs have been addressed
• No API implementations and no API clients have been developed

Experience APIs

Aggregator Mobile Auto Mobile Policy

Quote Creation Claim Holder Summary
API Submission API API

Process APIs

Policy Holder
create Summary API

search

Policy Holder Policy Options Motor Quote API Policy Search API Motor Claims Claims API
Search API Ranking API Submission API

System APIs

Motor Policy Home Policy Policy Options Motor Quote Motor Quote Motor Policy Home Policy Motor Claims Motor Claims Home Claims
Holder Search Holder Search Retrieval API Creation New Creation Addon Search API Search API Submission API Search API Search API
API API Business API Business API

Policy Admin Motor Claims Home Claims

System System System

Figure 56. All APIs in the Acme Insurance application network after addressing the functional
requirements of the "Aggregator Integration" product and "Customer Self-Service App"
product

See also Figure 50 and Figure 53.

Summary
• Acme Insurance’s immediate strategic initiatives require the creation of an "Aggregator
Integration" product and a "Customer Self-Service App" product
• The functional requirements of these products have been analyzed:
◦ Require 3 Experience APIs, 7 Process APIs and 10 System APIs
◦ Aggregator and Customer Self-Service Mobile App invoke Experience APIs
◦ API implementations of Experience APIs invoke Process APIs
◦ API implementations of Process APIs invoke other Process APIs or System APIs
◦ System APIs access the Policy Admin System, the Motor Claims System and the Home
Claims System, respectively
• 1 Process API and 2 System APIs originally identified for the "Aggregator Integration"
product have been reused in the "Customer Self-Service App" product
• Using API designer, RAML definitions for each API were sketched and simulated
• API Portals with API Console and API Notebook were created and published for each API

© 2017 MuleSoft Inc. 73

Anypoint Platform Architecture Application Network Design

• Anypoint Exchange entries for each API were published

© 2017 MuleSoft Inc. 74

Anypoint Platform Architecture Application Network Design

Chapter 5. Enforcing NFRs on the Level of API

Invocations Using Anypoint API Manager

Objectives
• Know the NFRs for the "Aggregator Integration" product and "Customer Self-Service App"
product
• Understand how Anypoint API Manager controlls API invocations
• Use API policies to enforce non-functional constraints on API invocations
• Understand the difference between enforcement of API policies in an API implementation
and an API proxy
• Register an API client for access to an API version
• Understand how to pass client ID/secret to an API
• Establish guidelines for API policies suitable for System APIs, Process APIs and Experience
APIs

5.1. Addressing the NFRs of the "Aggregator

Integration" product

5.1.1. NFRs for the "Create quote for aggregators" feature

Aggregators define strict SLAs for all insurance providers: they follow a commoditized business
model that capitalizes on high traffic volume to their site, with little or no willingness for
special treatment of individual insurance providers.

Consequently, the NFRs for the "Create quote for aggregators" feature are dictated primarily
by the Aggregator:

• Synchronous creation of up to 5 quotes:

◦ Aggregator-defined XML-formatted policy description is sent in HTTP POST request
◦ Up to 5 quotes may be returned in Aggregator-defined XML format in HTTP response
• Performance:
◦ Throughput: up to 1000 requs/s
◦ Response time: median = 200 ms, maximum = 500 ms at 1000 requs/s
▪ Invocations that exceed the maximum response time are timed-out by the
Aggregator

© 2017 MuleSoft Inc. 75

Anypoint Platform Architecture Application Network Design

• Security: HTTPS mutual authentication

• Reliability: quotes are legally binding and must not be lost

Create quote for

aggregators

Agg-defined Response time Must not lose Throughput HTTPS mutual

XML/HTTP < 500 ms, avg quotes 1000 requ/s authentication
interface 100 ms

Figure 57. Essential NFRs for the "Create quote for aggregators" feature

5.1.2. Meeting the NFRs for the "Create quote for aggregators"
feature using an Anypoint Platform-based Technology
Architecture
The implementation of the "Create quote for aggregators" feature must meet the NFRs listed
above. At this point you select a Technology Architecture rooted in Anypoint Platform features
that addresses these NFRs:

• XML/HTTP interface:
◦ Not architecturally significant, should be captured in API specification
• Throughput and response time:
◦ Very demanding
◦ Must be broken-down to APIs on all tiers
◦ Must be enforced, monitored and analyzed: Anypoint API Manager, Anypoint Analytics
◦ Anticipate the need for caching
◦ Select highly scalable Mule runtime: CloudHub
◦ Need to carefully manage load on Policy Admin System
• Must not lose quotes
◦ All-synchronous chain of API invocations, hence reliability requirement can be met by an
ACID operation on Policy Admin System
▪ If the Aggregator receives a quote then that quote must have been persisted in the
Policy Admin System
▪ If the Aggregator does not receive a quote due to a failure then a quote may still
have been persisted in the Policy Admin System, but the Aggregator user cannot refer
to that quote and it is therefore "orphaned"
• HTTPS mutual authentication:
◦ Possible with CloudHub Dedicated Load Balancers in an Amazon Web Services VPC

© 2017 MuleSoft Inc. 76

Anypoint Platform Architecture Application Network Design

◦ Should add client authentication on top of HTTPS mutual auth: Anypoint API Manager

5.2. Addressing the NFRs of the "Customer Self-Service

App" product

5.2.1. NFRs for the "Retrieve policy holder summary" feature

Initially, this feature is only part of Acme Insurance’s own "Customer Self-Service App"
product. But it has great potential for re-use, such as opening it up to external API consumers.
This would change the NFRs significantly.

• Synchronous HTTP request-response chain

• Performance:
◦ Currently ill-defined NFRs
◦ Aim for 100 requs/s
◦ Aim for avg response time of 2 s at 100 requs/s
• Security: HTTPS, OAuth 2.0-authenticated customer
• Consistency: Claims submitted from the Customer Self-Service Mobile App through the
"Submit auto claim" feature should be included as soon as possible in the summary
returned by the "Retrieve policy holder summary" feature

Retrieve policy
holder summary

OAuth2 Response Throughput HTTPS

time avg 2 s 100 requ/s

Figure 58. Essential NFRs for the "Retrieve policy holder summary" feature

5.2.2. Augmenting the Technology Architecture to support the

NFRs for the "Retrieve policy holder summary" feature
The implementation of the "Retrieve policy holder summary" feature must meet the NFRs
listed earlier - you augment the Technology Architecture selected earlier to ensure that these
NFRs can be realized:

• Throughput and response time:

◦ Do not seem overly challenging

© 2017 MuleSoft Inc. 77

Anypoint Platform Architecture Application Network Design

◦ But future use may change requirements significantly

◦ Select highly scalable Mule runtime: CloudHub: fits with existing Technology Architecture
• HTTPS:
◦ Document in RAML definition
◦ Ensure in API implementation
• OAuth 2.0:
◦ Enforce with Anypoint API Manager
◦ Requires Identity Provider for Client Management: PingFederate
• Consistency: to be addressed through event notifications, see Module 8

This means that Acme Insurance’s PingFederate instance, in addition to serving as an Identity
Provider for Identity Management, also assumes the responsibilities for OAuth 2.0 Client
Management. The C4E in collaboration with Acme IT configures the MuleSoft-hosted Anypoint
Platform accordingly.

5.2.3. NFRs for the "Submit auto claim" feature

Again, this feature is initially only used by Acme Insurance’s own "Customer Self-Service App"
product, but it has great potential for opening it up to external API consumers, which would
change the NFRs significantly.

Processing claim submissions entails numerous automated downstream validation and

processing steps, for example: * Storing images (typically of the accident) sent with the claim
submission in a Document Management System * Checking coverage of the vehicle and driver
involved in the accident with the Policy Admin System Performing these steps synchronously
with the claim submission would take too long. Processing claim submissions must therefore
be done asynchronously.

• Request over HTTP with claim submission, with asynchronous processing of the submission
• Performance:
◦ Currently ill-defined NFRs
◦ Aim for 10 requs/s
◦ No response time requirement because processing is asynchronous
• Security: HTTPS, OAuth 2.0-authenticated customer
• Reliability: claim submissions must not be lost
• Consistency: Claims submitted from the Customer Self-Service Mobile App through the
"Submit auto claim" feature should be included as soon as possible in the summary
returned by the "Retrieve policy holder summary" feature

© 2017 MuleSoft Inc. 78

Anypoint Platform Architecture Application Network Design

Submit auto claim

OAuth2 Must not Throughput Async HTTPS

lose claim 10 requ/s fulfillment
submissions

Figure 59. Essential NFRs for the "Submit auto claim" feature

5.2.4. Augmenting the Technology Architecture to support the

NFRs for the "Submit auto claim" feature
The implementation of the "Submit auto claim" feature must meet the NFRs listed earlier - you
add to the Technology Architecture accordingly:

• Performance and security requirements: as before for "Retrieve policy holder summary"
feature
• Async processing of claim submission and no claim submission loss:
◦ Select suitable messaging system to trigger asynchronous processing without message
loss:
▪ Anypoint MQ or Mule runtime persistent VM queues as implemented in CloudHub
▪ Anypoint MQ would be a new component in Acme Insurance’s Technology
Architecture
◦ Select suitable persistence mechanism to store correlation information for asynchronous
processing:
▪ Mule runtime Object Store as implemented in CloudHub
• Consistency: to be addressed through event notifications, see Module 8

The consistency requirement cannot be met just through communication with the Motor
Claims System alone, because once a claim submission is passed to the Motor Claims System
it goes through a sequence of transitions that are not visible from outside the Motor Claims
System, i.e., are not accessible through the "Motor Claims Search System API". Only after
some considerable time has passed becomes the newly submitted claim visible to the "Motor
Claims Search System API" and can therefore be returned via the normal interaction with the
Motor Claims System for the "Retrieve policy holder summary" feature. This requirement will
be addressed separately in Module 8.

5.3. Using Anypoint API Manager and API policies to

manage API invocations

© 2017 MuleSoft Inc. 79

Anypoint Platform Architecture Application Network Design

5.3.1. Reviewing types of APIs

What types of APIs are there?:

• REST APIs
◦ With API specification in the form of a RAML definition or OAS definition
◦ Without formal API specification
◦ Hypermedia-enabled REST APIs
• Non-REST APIs
◦ GraphQL APIs
◦ SOAP web services (APIs)
◦ JSON-RPC, gRPC, …

5.3.2. API management on Anypoint Platform

• Using Anypoint API Manager and API policies
• On the level of HTTP
• Applicable to all types of HTTP/1.x APIs
◦ Hence not applicable to WebSocket APIs or HTTP/2 APIs like gRPC APIs
• Special support for RAML-defined APIs
◦ Allow definition of resource-level instead of just endpoint-level API policies

5.3.3. Defining API policy

See the corresponding glossary entry.

5.3.4. Enforcement of API policies

On Anypoint Platform, API policies are always enforced from within a Mule application
executing in a Mule runtime:

• An API implementation implemented as a Mule application can embed the feature of

enforcing API policies
• Alternatively, a separate Mule application called an API proxy can be deployed infront of the
API implementation proper to enforce API policies for the API exposed by that API
implementation

The API policies themselves are not included into any of these Mule applications, just the
capability of enforcing API policies. This is true for both the API policy template (code) and API

© 2017 MuleSoft Inc. 80

Anypoint Platform Architecture Application Network Design

policy definition (data). API policies are downloaded at runtime from Anypoint API Manager
into the Mule application that enforces them.

API Policy

API Policy API Policy

template definition

API Policy
enforcement

Mule runtime
API proxy
API
implementation

HTTP/S HTTP/S
HTTP/S

API API client

implementation

Figure 60. API policies, their structure and enforcement

5.3.5. Exercise 5: Pros and cons of API policy enforcement

embedded in the API implementation versus in an API proxy
Compare enforcement of API policies directly in the API implementation and in a separate API
proxy:

• Compile a list of advantages for each API policy enforcement site

Solution

• With API implementations not deployed to Mule runtimes the use of API proxies is
mandatory.

© 2017 MuleSoft Inc. 81

Anypoint Platform Architecture Application Network Design

• With API proxies API policy enforcement and API implementation can be scaled separately,
both horizontally as well as vertically.
• Number of nodes approx. doubles when API proxies are used.
• Deployment architecture and CI/CD is more complex with API proxies.
• API proxies can shield API implementations from DoS or similar attacks, which would be
rejected by the API proxies and therefore wouldn’t even reach the API implementations.
However, because all API invocations to an API implementation go through the API proxies
for that API, the DoS attack still has the potential to disrupt the service offered by that API
simply by swamping the API proxies with requests.
• API proxies can be deployed to a different subnet/VPC than their underlying API
implementations.
◦ Therefore Experience APIs can use API proxies deployed to a DMZ, while Process APIs
and System APIs, which often do not require protection via a DMZ, can use embedded
enforcement of API policies.

5.3.6. Managing APIs with Anypoint API Manager

Anypoint API Manager is the component of Anypoint Platform which

• allows the configuration of API policies for a given API version

◦ by selecting an API policy template and parameterizing it with an API policy definition
• allows the creation of custom API policies (templates) in addition to the ones provided by
Anypoint API Manager out-of-the-box
• is contacted from the site of API policy enforcement to download all API policies that must
be enforced
• allows management of API clients (applications) that have requested access to an API
version
• allows the definition of alerts based on the characteristics of API invocations
• gives access to Anypoint Analytics

© 2017 MuleSoft Inc. 82

Anypoint Platform Architecture Application Network Design

Figure 61. Anypoint API Manager displaying some of the APIs in the Acme Insurance
application network

5.3.7. Selectively applying an API policy to some resources and

methods of an API
APIs defined with a RAML definition can apply API policies not just to the entire API endpoint
but to selected combinations of API resources and HTTP methods. This configuration is
performed when configuring the API policy and is then applied at the time when the API policy
is enforced. Because OpenAPI documents can be converted to RAML definitions, this option is
also available for APIs defined with OpenAPI API specifications.

5.3.8. API policies available on Anypoint Platform

Anypoint Platform provides the following API policies (API policy templates, to be precise) for
managing non-functional cross-cutting concerns on APIs:

• Compliance-related API policies

◦ Client ID enforcement
◦ Cross-Origin Resource Sharing (CORS) (control thereof)
• Security-related API policies
◦ HTTP Basic Authentication
◦ IP blacklist

© 2017 MuleSoft Inc. 83

Anypoint Platform Architecture Application Network Design

◦ IP whitelist
◦ JSON threat protection
◦ XML threat protection
◦ LDAP security manager (injection thereof)
◦ Simple security manager (injection thereof)
◦ OAuth 2.0 access token enforcement using external provider
◦ OpenAM access token enforcement
◦ PingFederate access token enforcement
• QoS-related API policies
◦ SLA-based
▪ Rate Limiting - SLA-based
▪ Throttling - SLA-based
◦ non-SLA-based
▪ Rate Limiting
▪ Throttling

Anypoint Platform also allows arbitrary custom API policies to be implemented as Mule
applications.

© 2017 MuleSoft Inc. 84

Anypoint Platform Architecture Application Network Design

API Policy

Custom Compliance Security QoS Policy

Policy Policy Policy

Cross-Origin HTTP Basic LDAP OAuth 2.0 IP blacklist JSON threat Rate Rate
Resource Authenticati security access token protection Limiting - Limiting
Sharing on manager enforcement SLA-based

Client ID Simple PingFederate IP whitelist XML threat Throttling - Throttling

enforcement security access token protection SLA-based
manager enforcement

OpenAM
authentication
access token
enforcement

Security OAuth 2.0 SLA-based Non-SLA-

Manager Enforcement Policy based Policy
Injector Policy

Client ID- Identity SLA Tier

Based Policy Provider

Figure 62. Classification of API policies (templates) available out-of-the-box in Anypoint

Platform and the ability to define custom API policies. Only blue API policies are concrete, the
others elements are included for clarification

5.3.9. Introducing compliance-related API policies

Two of Anypoint Platform’s API policies can be categorized as related to compliance:

• Client ID enforcement
• CORS control

Client ID enforcement will be discussed in Section 5.3.18.

The CORS policy participates in interactions with API clients defined by CORS (Cross-Origin
Resource Sharing):

• Rejects HTTP requests whose Origin request header does not match configured origin
domains
• Sets Access-Control- HTTP response headers to match configured cross-origins, usage of
credentials, etc.
• Responds to CORS pre-flight HTTP OPTIONS requests (containing Access-Control-
Request- request headers) as per the policy configuration (setting Access-Control-
response headers)

The CORS policy can be important for Experience APIs invoked from a browser.

© 2017 MuleSoft Inc. 85

Anypoint Platform Architecture Application Network Design

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS for a good

discussion of CORS.

5.3.10. Introducing security-related API policies

Anypoint Platform provides security-related API policies in the following categories:

• Authentication
• IP-based access control
• Payload threat protection

5.3.11. Introducing OAuth 2.0 token enforcement API policies

OAuth 2.0-based API policies have a dependency on a suitable Identity Provider for Client
Management:

• OpenAM access token enforcement requires OpenAM as an Identity Provider

• PingFederate access token enforcement requires PingFederate as an Identity Provider
• OAuth 2.0 access token enforcement using external provider requires an external OAuth
2.0 provider that just validates access tokens and is not configured in Anypoint Platform
Client Management
◦ Client IDs/secrets of API clients registered with Anypoint Platform not kept in sync with
such an external OAuth 2.0 provider
▪ As would be the case if Client Management were configured at the Anypoint Platform-
level
◦ The Mule OAuth 2.0 provider is a custom-developed application component that can
serve as such an external OAuth 2.0 provider
▪ See template in Anypoint Exchange
◦ Use of this API policy is discouraged

5.3.12. Understanding the interaction between Anypoint

Platform, PingFederate and the access token enforcement
policy
When an Identity Provider such as PingFederate is configured for Client Management on
Anypoint Platform, then API clients who register with Anypoint Platform for access to an API,
and therefore receive client ID and secret, are kept in sync between Anypoint Platform and the
Identity Provider. This is in addition to the Identity Provider validating OAuth 2.0 access tokens
for every API invocation to an API that is protected by the matching access token enforcement

© 2017 MuleSoft Inc. 86

Anypoint Platform Architecture Application Network Design

API policy - such as PingFederate access token enforcement.

Anypoint Platform PingFederate Mule runtime

(AP) (PF) (MR)

One-off creation of "AP token validation client"

When the organization is first configured

1 HTTP POST /pf-ws/rest/oauth/clients
in AP to use PF for client management.

Configuration of every API client in AP

When an API client application

2 HTTP PUT/POST/DELETE /pf-ws/rest/oauth/clients requests access to an API in AP,
the OAuth client is also created in PF.

Token validation

When an API with the

PingFederate access token enforcement policy
is called, the MR enforcing that policy
3 HTTP POST /as/token.oauth2
validates the caller's access token with PF.
AP uses the "AP token validation client"
credentials to authenticate this call to PF.

Anypoint Platform PingFederate Mule runtime

(AP) (PF) (MR)

Figure 63. The interaction between Anypoint Platform, PingFederate as an Identity Provider
configured for Client Management, and a Mule runtime enforcing the PingFederate access
token enforcement API policy

5.3.13. Introducing API policies for HTTP Basic Authentication

In addition to the above OAuth 2.0-based API policies, Anypoint Platform also supports an API
policy that enforces HTTP Basic Authentication backed by one of these Security Managers:

• Simple security manager (for testing only)

• LDAP security manager

The Security Manager is made available to the HTTP Basic Authentication API policy through its
own "Security Manager Injector" API policy.

5.3.14. Introducing API policies protecting against JSON and

XML threats
These policies guard against attacks that work by sending over-sized HTTP request bodies to
an API. They work by limiting the size of XML and JSON bodies by setting upper limits on

© 2017 MuleSoft Inc. 87

Anypoint Platform Architecture Application Network Design

• nesting levels
• string length
• number of elements

etc.

5.3.15. Introducing QoS-related API policies

Anypoint Platform currently provides two types of API policies related to QoS (Quality of
Service) of APIs:

• Rate Limiting
• Throttling

Both types of policies enforce a throughput limit defined in number of API invocations per unit
of time:

• Rate Limiting rejects requests when the throughput limit has been reached
• Throttling queues requests beyond the throughput limit

Anypoint Platform provides two different ways to define the throughput limit enforced by these
QoS-related API policies:

• Non-SLA-based, where a throughput limit is defined on the API policy definition associated
with a particular API (version)
◦ Limit is enforced for that API (version) and the sum of all its API clients, ignoring the
identity of the API clients
• SLA-based, where a throughput limit is defined in an SLA tier
◦ API clients must register with the API (version) at a particular SLA tier
◦ Limit is enforced separately for each registered API client

Thus SLA-based API policies require the API client to identify itself with a client ID: see Section
5.3.18. On the other hand, the API clients of APIs without client ID-based API policies can
remain anonymous.

When an API client invokes an API that has any QoS-related API policy defined, then the HTTP
response from the API invocation contains HTTP response headers that inform the API client of
the remaining capacity as per the QoS-related API policy:

• X-RateLimit-Reset: remaining time in milliseconds until the end of the current limit
enforcement time window

© 2017 MuleSoft Inc. 88

Anypoint Platform Architecture Application Network Design

• X-RateLimit-Limit: overall number of API invocations allowed in the current limit

enforcement time window
• X-RateLimit-Remaining: actually remaining number of API invocations in the current limit
enforcement time window

5.3.16. Introducing Anypoint Platform SLA tiers for APIs

Anypoint Platform (and, specifically Anypoint API Manager) supports the notion of SLA tiers
(Service Level Agreement tiers) to enable different classes of API clients to receive different
degrees of QoS.

If an API (version) has SLA tiers defined then every API client that registers for access to that
API (version) is assigned to exactly one SLA tier and is thereby promised the QoS offered by
that SLA tier.

An SLA tier for an API (version) managed on Anypoint Platform

• defines one or more throughput limits, i.e., limits on the number of API invocations per time
unit
◦ E.g., 100 requs per second and simultaneously 1000 requs per hour
◦ These limits are per API client and API version
• requires either manual approval or supports automatic approval of API clients requesting
usage of that SLA tier
◦ typically at least SLA tiers that confer high QoS guarantees require manual approval

To enforce the throughput limits of an SLA tier, SLA-based Rate Limiting or Throttling API
policies need to be configured for that API version. The violation of the QoS defined by an SLA
tier can be monitored and reported with Anypoint Analytics and can also be the source of
alerts.

API clients sending API invocations to an API with enforced SLA tiers must identify themselves
via a client ID/client secret pair sent in the API invocation to the API.

5.3.17. Registering API clients with an Anypoint Platform-

managed API
API clients that wish to invoke a non-public API must be registered for access to that API
(version). Access must be requested by the API consumer for that particular API client through
the API Portal for that API, using an Anypoint Platform user account with permissions to view
API Portals.

© 2017 MuleSoft Inc. 89

Anypoint Platform Architecture Application Network Design

In Anypoint Platform, an API client requesting access or having been granted access to an API
version is called "application" or "client application".

Once the registration request is approved - either automatically or manually - the API
consumer receives a client ID and client secret that must be supplied by the nominated API
client in subsequent API invocations to that API.

Figure 64. An API consumer using the API Portal for "Aggregator Quote Creation Experience
API" version v5 to request access to that API (version) for an API client (application) called
Aggregator

Figure 65. Anypoint API Manager web UI showing the Aggregator as the only API client
(application) registered for access to the "Aggregator Quote Creation Experience API" version
v5. The Aggregator is registered with the "standard" SLA tier

5.3.18. Client ID-based API policies

Anypoint Platform provides several API policies that require API clients to identify themselves
with a client ID. By default, API clients are also required to send a client secret.

Client ID and secret must be supplied in the API invocation as defined by the API policy.

© 2017 MuleSoft Inc. 90

Anypoint Platform Architecture Application Network Design

Available options are:

• as query parameters
◦ by default client_id and client_secret
• as custom request headers
• in the standard Authorization header as defined by HTTP Basic Authentication
◦ where client ID takes the role of username and client secret that of password

The client ID-based API policies available in Anypoint Platform are:

• Client ID enforcement
◦ Enforces presence and validity of client ID (and typically also client secret)
• Rate Limiting - SLA-based
◦ Rejects requests when the throughput limit defined in the SLA tier for the API client has
been reached
• Throttling - SLA-based
◦ Queues requests beyond the throughput limit

SLA-based Rate Limiting and Throttling require the SLA tier of the API client making the
current API invocation to be retrieved by the client ID supplied in the API invocation. These
two API policies therefore implicitly also enforce the presence and validity of the client ID, and,
as a convenience, also the client secret. They therefor subsume the functionality of the Client
ID enforcement API policy.

5.3.19. Exercise 6: Select API policies for all tiers in Acme

Insurance's application network
1. Revisit the API policies supported out-of-the-box by Anypoint Platform
2. Select one Experience API, one Process API and one System API from the APIs involved in
the "Aggregator Integration" product
3. For each of these APIs, select all API policies that you would recommend applying to that
API
4. Are there any API policies missing that you would want to apply?

© 2017 MuleSoft Inc. 91

Anypoint Platform Architecture Application Network Design

Experience APIs

Aggregator
Quote Creation
API

create
Process APIs

Policy Holder Policy Options Motor Quote API

Search API Ranking API

System APIs

Motor Policy Home Policy Policy Options Motor Quote Motor Quote
Holder Search Holder Search Retrieval API Creation New Creation Addon
API API Business API Business API

Policy Admin
System

Figure 66. All APIs collaborating for the "Aggregator Integration" product

See Figure 62.

Solution

See Section 5.3.20, Section 5.3.21, Section 5.3.22 and Section 5.3.23.

5.3.20. Choosing appropriate API policies for System APIs

Acme Insurance’s C4E defines the following guidelines for defining API policies on System
APIs:

• Must always be protected by SLA-based API policies that require manual approval
• SLA-based Rate Limiting or Throttling API policies must enforce the QoS of the chosen SLA
tier
• IP whitelisting to the IP address range of the API implementations of Process APIs
(assuming they are in a VPC)
• This enforces strict compliance for this critical class of APIs

Acme Insurance applies these guidelines to all System APIs in their application network.

© 2017 MuleSoft Inc. 92

Anypoint Platform Architecture Application Network Design

Figure 67. API policies defined for the "Policy Options Retrieval System API"

5.3.21. Choosing appropriate API policies for Process APIs

Acme Insurance’s C4E defines the following guidelines for defining API policies on Process
APIs:

• May define non-SLA-based API policies and omit Client ID enforcement

◦ This lowers the barrier of reusing Process APIs as widely as possible across the
application network
◦ On the other hand, it precludes knowledge of API clients and analyses per API client,
which are highly desirable
• Rate Limiting or Throttling API policies must enforce the published overall QoS guarantees
• IP whitelisting to the IP address range of the API implementations of Process APIs and
Experience APIs (assuming they are in VPCs)

Acme Insurance applies these guidelines to all Process APIs in their application network.

© 2017 MuleSoft Inc. 93

Anypoint Platform Architecture Application Network Design

Figure 68. API policies defined for the "Policy Holder Search Process API"

5.3.22. Choosing appropriate API policies for Experience APIs

API policies on Experience APIs depend critically on the nature of the top-level API client for
which an Experience API is intended. Acme Insurance’s C4E therefore first defines API policies
for concrete Experience APIs, generalizing to Acme Insurance-wide guidelines in a second
step.

For the "Aggregator Quote Creation Experience API" consumed by the Aggregator you define
the following:

• One SLA tier for the required 1000 requs/s

◦ Makes this SLA explicit and allows monitoring and reporting on the SLA
• SLA-based Rate Limiting (not Throttling, to reduce resource consumption)
• IP whitelist to complement TLS mutual authentication
• XML threat protection

© 2017 MuleSoft Inc. 94

Anypoint Platform Architecture Application Network Design

Figure 69. API policies defined for the "Aggregator Quote Creation Experience API"

For the "Mobile Policy Holder Summary Experience API" and "Mobile Auto Claim Submission
Experience API" consumed by Acme Insurance’s own Customer Self-Service Mobile App you
define:

• Non-SLA-based Rate Limiting (not Throttling) for 100 requs/s for "Mobile Policy Holder
Summary Experience API" and 10 requs/s for "Mobile Auto Claim Submission Experience
API"
• Client ID enforcement
• OAuth 2.0 access token enforcement
• JSON threat protection

Figure 70. API policies defined for the "Mobile Policy Holder Summary Experience API"

From this the following general guidelines for API policies on Experience APIs emerge:

© 2017 MuleSoft Inc. 95

Anypoint Platform Architecture Application Network Design

• Rate Limiting instead of Throttling to reduce resource consumption in case of excessive

number of API invocations, such as during DoS attacks
• Some form of enforcement of API client or user identity
• Protection against oversized JSON/XML payloads

5.3.23. Reviewing API policies for the APIs involved in the

"Create quote for aggregators" feature
Aggregator

XML threat
protection

Experience APIs

Aggregator Rate
Quote Creation Limiting -
API SLA-based

create
Process APIs
Throttling
Policy Holder Policy Options Motor Quote API
Search API Ranking API

System APIs IP whitelist

Motor Policy Home Policy Policy Options Motor Quote Motor Quote
Holder Search Holder Search Retrieval API Creation New Creation Addon
API API Business API Business API

Throttling -
SLA-based

Policy Admin
System

Figure 71. API policies applied to APIs in all tiers collaborating for the "Create quote for
aggregators" feature

5.3.24. Reviewing API policies for the APIs involved in the

"Retrieve policy holder summary" feature

© 2017 MuleSoft Inc. 96

Anypoint Platform Architecture Application Network Design

JSON threat
Customer Self- protection
Service Mobile
App

OAuth 2.0
Experience APIs access token
enforcement
Mobile Policy
Holder Summary
API
Client ID
enforcement
Process APIs

Policy Holder
Summary API
Rate
search Limiting

Policy Holder Policy Search API Claims API

Search API

Throttling
System APIs

Motor Policy Home Policy Motor Policy Home Policy Motor Claims Home Claims
Holder Search Holder Search Search API Search API Search API Search API
API API
IP whitelist

Policy Admin Motor Claims Home Claims

System
System System
Throttling -
SLA-based

Figure 72. API policies applied to APIs in all tiers collaborating for the "Retrieve policy holder
summary" feature

5.3.25. Reviewing API policies for the APIs involved in the

"Submit auto claim" feature

© 2017 MuleSoft Inc. 97

Anypoint Platform Architecture Application Network Design

JSON threat
Customer Self- protection
Service Mobile
App

OAuth 2.0
access token
enforcement

Experience APIs

Mobile Auto
Claim Client ID
Submission API enforcement

Process APIs

Motor Claims Rate

Submission API Limiting

System APIs
Throttling
Motor Claims
Submission API

IP whitelist

Motor Claims
System

Throttling -
SLA-based

Figure 73. API policies applied to APIs in all tiers collaborating for the "Submit auto claim"
feature

5.3.26. Reflecting the application of API policies in the RAML

definition of an API
Many API policies change the HTTP request and/or HTTP response of API invocations subtly, for
instance by

• requiring certain HTTP request headers, e.g., Authorization

• requiring certain query parameters, e.g., client_id
• adding HTTP response headers, e.g., X-RateLimit-Limit

or in other similar ways.

These changes to the contract between API client and API implementation must be reflected in

© 2017 MuleSoft Inc. 98

Anypoint Platform Architecture Application Network Design

the RAML definition of the API. In other words, applying API policies often requires the RAML
definition to be changed to reflect the applied API policies.

In the case of security-related API policies, RAML has specific support through
securitySchemes, e.g. of type OAuth 2.0 or Basic Authentication. In other cases, RAML
traits are a perfect mechanism for expressing the changes to the API specification introduced
by the application of an API policy.

The C4E should own the definition of reusable RAML fragments for all commonly used API
policies in Acme Insurance. These RAML fragments should be published to Anypoint Exchange
to encourage consumption and reuse.

Summary
• The NFRs for the "Aggregator Integration" product and "Customer Self-Service App"
product are a combination of constraints on throughput, response time, security and
reliability
• Anypoint API Manager and API policies control APIs and invocations of APIs and can impose
NFRs on that level in the areas of:
◦ Compliance
◦ Security
◦ QoS
• API policies can be enforced directly in an API implementation that is a Mule application or
in an API proxy
• Client ID-based API policies require API clients to be registered for access to an API version
◦ Must pass client ID/secret with every API invocation
• The Acme Insurance C4E has defined guidelines for the API policies to apply to System
APIs, Process APIs and Experience APIs
◦ C4E has created reusable RAML fragments for API policies and published them to
Anypoint Exchange

© 2017 MuleSoft Inc. 99

Anypoint Platform Architecture Application Network Design

Chapter 6. Designing Effective APIs

Objectives
• Appreciate the importance of contract-first API design and RAML fragments
• Understand semantic versioning-based API versioning and where to expose what elements
of an API’s version
• Choose between Enterprise Data Model and Bounded Context Data Models
• Consciously design System APIs to abstract from backend systems
• Apply HTTP-based asynchronous execution of API invocations and caching to meet NFRs
• Understand idempotent HTTP methods and HTTP-native support for optimistic concurrency

6.1. Understanding API design on Anypoint Platform

6.1.1. API design with Anypoint Platform and RAML

MuleSoft advocates API specification-driven, i.e., contract-first, API design:

1. Start by creating the API specification, ideally in the form of a RAML definition
2. Simulate interaction with the API based on the API specification
3. Gather feedback from potential future API consumers
4. Publish documentation and API-related assets, including the RAML definition of the API
5. Only then implement the API

This is the approach that has been followed in Module 4.

Anypoint Platform has support for API specifications in the form of

• RAML definitions
◦ First-class support in all relevant components
• OpenAPI (OAS, Swagger) documents
◦ Import/export in API designer
◦ Import in Anypoint Exchange
• WSDL documents
◦ Import in Anypoint Exchange and Anypoint API Manager

© 2017 MuleSoft Inc. 100

Anypoint Platform Architecture Application Network Design

6.1.2. Identifying and publishing reusable RAML fragments

It is not only entire APIs that can be reused in an application network: if an API specification is
defined in RAML then it is likely that it makes use of concepts that are reusable in other
contexts. These reusable parts of a RAML definition are called RAML fragments. RAML
fragments define aspects of the interface between an API client and an API implementation of
the API in question - they are partial interface definitions.

With the support of the Acme Insurance C4E you isolate these and other RAML fragments from
the APIs identified so far:

• RAML SecurityScheme definitions for HTTP Basic Authentication and OAuth 2.0
• A RAML Library containing resourceTypes to support collections of items
• A RAML Library containing resourceTypes and traits to support asynchronous
processing of API invocations with polling
• RAML traits for the API policies recommended at Acme Insurance, amongst them:
◦ Client ID enforcement
◦ SLA-based and non-SLA-based Rate Limiting and Throttling

These RAML fragments are represented in Anypoint Platform

• as Anypoint Design Center projects

• as Anypoint Exchange assets

This makes them discoverable and reusable within the Acme Insurance application network.

© 2017 MuleSoft Inc. 101

Anypoint Platform Architecture Application Network Design

Figure 74. Some RAML fragments identified by the Acme Insurance C4E and by MuleSoft and
made available in the public and Acme Insurance-private Anypoint Exchange, respectively

6.2. Versioning APIs

6.2.1. Strategy for API versions on Anypoint Platform

Follow a split strategy on versioning APIs:

1. Try very hard to make all changes to APIs backwards-compatible

2. But assume that incompatible changes will be needed and hence version your APIs

An API versioning approach is visible throughout the application network and should therefore
be standardized by the C4E.

On Anypoint Platform the version of an API is visible in these places:

• The URL of the API endpoint

• The RAML definition of the API
• The Anypoint API Manager entry for the API
• The Anypoint Exchange entry (asset) for the API

© 2017 MuleSoft Inc. 102

Anypoint Platform Architecture Application Network Design

6.2.2. Understanding semantic versioning of APIs on Anypoint

Platform
Use semantic versioning with major, minor and patch version numbers for APIs:
major.minor.patch:

• Major versions introduce backwards-incompatible changes in the structure of the API that
require API clients to adapt
• Minor versions introduce backwards-compatible changes to the API that do not require API
clients to change, unless the API client wants to take advantage of the newly introduced
changes.
• Patch versions introduce small fully backwards-compatible fixes, such as documentation
changes

If semantic versioning is followed then version 1.2.3 of an API is a perfect stand-in for version
1.1.5, and so all API clients that have previously used version 1.1.5 can be upgraded "silently"
to use version 1.2.3 instead. For this reason, often only the major version of an API is made
visible to API clients. This means that only the major version of the API should be visible in

• The RAML definition of the API

• The URL of the API endpoint
• The Anypoint API Manager entry for the API

While the Anypoint Exchange entry (asset) for the API should/must surface the full semantic
version of the API, including a patch version. This is because the Anypoint Exchange entry of
type "REST API" represents the RAML definition itself - see Section 4.3.11.

6.2.3. Versioning API endpoint URLs

In what part of a URL to surface the API version:

• Encode the version just in the URL path, e.g., http://acmeins-policyholdersummary-

papi.cloudhub.io/v1
◦ Requires a DNS lookup of acmeins-policyholdersummary-papi.cloudhub.io to resolve
to an API implementation (or API proxy) that supports all version of the API, including
future major versions
◦ Alternatively, all API invocations must be routed on the server-side to the API
implementation that supports the requested version
▪ Supported through URL mapping rules in CloudHub Dedicated Load Balancers
• Encode the version just in the hostname, e.g., http://acmeins-policyholdersummary-papi-

© 2017 MuleSoft Inc. 103

Anypoint Platform Architecture Application Network Design

v1.cloudhub.io/
◦ Allows future (major) versions of the API to be backed by different API implementations
(or API proxies) without having to do URL rewriting
• Encode the version in the hostname and the URL path, e.g., http://acmeins-
policyholdersummary-papi-v1.cloudhub.io/v1
◦ Redundant but allows the URL path on its own to identify the requested API version,
without URL rewriting
◦ Allows the same API implementation to expose endpoints for more than one major
version

6.2.4. API versioning guidelines

The Acme Insurance C4E defines the following API versioning guidelines:

• Only expose major API versions as v1, v2, etc. in RAML definition, API endpoint URL and
Anypoint API Manager entries
• In the API endpoint URL expose the major API version only in the URL path
◦ E.g., http://acmeins-policyholdersummary-papi.cloudhub.io/v1
◦ Requires future major versions to either be implemented in same API implementation or
to route API invocations with URL mapping rules
• Publish to Anypoint Exchange using the full semantic version

6.2.5. Deprecation of API versions in Anypoint API Manager

See Section 9.4.

6.3. Deciding granularity, separation and abstraction of

APIs

6.3.1. Where we are along Acme Insurance's application

network journey
At this point you have

• identified APIs to be developed and reused

• assigned functional responsibilities to them
• ensured alignment of API functionalities to business processes
• documented the current understanding of these APIs in RAML definitions, API Portals

© 2017 MuleSoft Inc. 104

Anypoint Platform Architecture Application Network Design

• made documentation and API-related assets discoverable in the Acme Insurance Developer
Portal and Anypoint Exchange
• designed a high-level Application Architecture that identifies API interactions
• sketched a Technology Architecture, using components from Anypoint Platform, that is
likely to support all NFRs

The above characterizes Acme Insurance’s nascent application network.

You will now look in more detail at the APIs (this module) and their API implementations (next
module) and address the most important design questions that arise in doing so. You will
restrict this investigation to architecturally significant design topics, i.e., you will ignore design
questions that have no implication for the effectiveness of the resulting application network.

6.3.2. Defining API data model

The APIs you have identified and started defining in RAML definitions exchange data
representations of business concepts, mostly in JSON format. Examples are:

• The JSON representation of the Policy Holder of a Motor Policy returned by the "Motor Policy
Holder Search System API"
• The XML representation of a Quote returned by the "Aggregator Quote Creation Experience
API" to the Aggregator
• The JSON representation of a Motor Quote to be created for a given Policy Holder passed to
the "Motor Quote Process API"
• The JSON representation of any kind of Policy returned by the "Policy Search Process API"

All data types that appear in an API (i.e., the interface) form the API data model of that API.
The API data model should be specified in the RAML definition of the API. Data models are
clearly visible across the application network because they form an important part of the
interface contract for each API.

The API data model is conceptually clearly separate from similar models that may be used
inside the API implementation, such as an object-oriented or functional domain model, and/or
the persistence data model used by the API implementation. Only the API data model is visible
to API clients - all other forms of models are not.

6.3.3. Enterprise Data Model versus Bounded Context Data

Models
Data types in the data models of different APIs can be more or less coordinated:

© 2017 MuleSoft Inc. 105

Anypoint Platform Architecture Application Network Design

• In an Enterprise Data Model there is exactly one canonical definition of each data type,
which is reused in in all APIs that require that data type, within all of Acme Insurance
◦ E.g., one definition of Policy that is used in APIs related to Motor Claims, Home Claims,
Motor Underwriting and Home Underwriting
• In a Bounded Context Data Model several Bounded Contexts are identified within Acme
Insurance by their usage of common terminology and concepts. Each Bounded Context
then has its own, distinct set of data type definitions - the Bounded Context Data Model.
The Bounded Context Data Models of separate Bounded Contexts are formally unrelated,
although they may share some names. All APIs in a Bounded Context reuse the Bounded
Context Data Model of that Bounded Context
◦ E.g., the Motor Claims Bounded Context has a distinct definition of Policy that is
unrelated to the definition of Policy in the Home Underwriting Bounded Context
• In the extreme case, every API defines its own data model. Put differently, every API is in a
separate Bounded Context with its own Bounded Context Data Model.

Also see [Ref13].

6.3.4. Selecting between Enterprise Data Model and Bounded

Context Data Models
• The coordination of data models between APIs adds overhead, which can become
significant if APIs are owned by separate groups
• This is one reason why Enterprise Data Models, although a seemingly attractive idea, are
often not successful
• If there is no successful Enterprise Data Model, it is most pragmatic to use Bounded
Context Data Models
• If there is a successful Enterprise Data Model, then all Process APIs and System APIs should
reuse that Enterprise Data Model as much as possible
• The data model of Experience APIs, on the other hand, is determined by the needs of the
top-level API clients (such as user-visible apps) and thus is very unlikely to be served by an
Enterprise Data Model
◦ E.g., Aggregator or Customer Self-Service Mobile App are unlikely to be served well be
an Enterprise Data Model

6.3.5. Identifying Bounded Contexts and Bounded Context Data

Models
Because Acme Insurance does not have a well-defined, successful Enterprise Data Model, it
uses Bounded Context Data Models. To do so,

© 2017 MuleSoft Inc. 106

Anypoint Platform Architecture Application Network Design

• identify Bounded Contexts

• assign each API to exactly one Bounded Context
• define a Bounded Context Data Model for each Bounded Context based pragmatically on the
needs of the APIs in that Bounded Context
• and reuse the Bounded Context Data Model in the APIs of that Bounded Context

In general, do not assign APIs in different tiers of API-led connectivity, i.e. Experience APIs,
Process APIs and System APIs, to the same Bounded Context: it is unlikely that they use
concepts and data types identically, i.e. it is unlikely that they share a data model.

To identify Bounded Contexts

• start with the organizational structure

◦ e.g., Motor Claims, Home Claims, Motor Underwriting and Home Underwriting
• if in doubt prefer smaller Bounded Contexts
• if still in doubt put each API in its own Bounded Context
◦ i.e., do not coordinate data models between APIs

A Bounded Context Data Model should be published as RAML fragments (RAML types, possibly
in a RAML Library) in Anypoint Design Center and Anypoint Exchange, so that it can be easily
re-used from all APIs in a Bounded Context. The Acme Insurance C4E owns this activity and
the harvesting of data types from existing APIs.

6.3.6. Exercise 7: Identify Bounded Contexts in Acme

Insurance's application network
You have already identified a large number of APIs:

1. Delineate the boundaries of meaningful Bounded Contexts so that

a. every API belongs to exactly one Bounded Context
b. there is more than one Bounded Context overall (i.e., no Enterprise Data Model)
2. Discuss the implications of the identified Bounded Context Data Models for data
transformation

See Figure 56.

Solution

For instance:

© 2017 MuleSoft Inc. 107

Anypoint Platform Architecture Application Network Design

• Motor and home policy administration, although both implemented by the same Mainframe-
based Policy Admin System, are distinct Bounded Contexts, not only because they serve
different teams within Acme Insurance but also because they are implemented by different
data schemata and database tables in the Mainframe.

6.3.7. Mapping between Bounded Context Data Models

Distinct Bounded Context Data Models necessitate data transformation whenever APIs from
different Bounded Contexts need to cooperate. More precisely:

• An API implementation (the caller) belonging to an API in a given Bounded Context

• that must invoke an API (the called) in a different Bounded Context
• must transform the Bounded Context Data Model of the called API
• to its own Bounded Context Data Model

This approach to mapping between Bounded Context Data Models is called anticorruption
layer. There are other variants of mapping between Bounded Context Data Models, depending
on where transformation occurs, but this falls into the domain of detailed design and is not
visible on the Enterprise Architecture level and therefore out-of-scope for this discussion.

API implementations implemented as Mule applications can draw on the advanced data
mapping capabilities of Anypoint Studio and the Mule runtime for implementing data
transformations of this kind.

6.3.8. Understanding relationships when integrating between

Bounded Contexts
More generally, there are important power relationships at play whenever an API
implementation from one Bounded Context invokes an API from another Bounded Context. For
instance, using DDD terminology:

• Partnership: Coordination of caller and called in terms of features and timeline

• Customer/Supplier: Caller requests features from the called, who may have to coordinate
many callers' feature requests.
• Conformist: Caller must work with whatever called provides

6.3.9. Exercise 8: Identify Bounded Context power

relationships
Based on the previous identification of Bounded Contexts within Acme Insurance’s application
network, or drawing on your own experience,

© 2017 MuleSoft Inc. 108

Anypoint Platform Architecture Application Network Design

• Identify at least one example for each type of relationship, i.e.,

◦ Partnership
◦ Customer/Supplier
◦ Conformist

See Figure 56.

Solution

• Partnership: Motor Claims BC and Motor Policy BC, because located in same LoB and
cooperate on "Customer Self-Service App" product
• Customer/Supplier: Home Claims BC towards operators of Home Claims System, because
outsourced and externally developed
• Conformist: Motor Quote BC towards Aggregator, because Aggregator determines interface

6.3.10. Abstracting from backend systems with System APIs

System APIs mediate between backend systems and Process APIs:

• Should there be one System API per backend system or many?

• How much of the intricacies of the backend system should be exposed in the System APIs
in front of that backend system?
◦ How much to abstract backend system data models in API data model of the System
APIs for that backend system?

General guidance:

• If an Enterprise Data Model is in use then System APIs should translate between the
Enterprise Data Model and the native data model of the backend system
• If not then System APIs should expose data approximately as defined in the backend
system
◦ same semantics and naming as backend system
◦ but for only one Bounded Context - backend system often are Big Balls of Mud that
cover many Bounded Contexts
◦ lightly sanitized
▪ e.g., using idiomatic JSON data types and naming, correcting misspellings, …
◦ expose all fields needed for the given Bounded Context, but not more
◦ making good use of REST conventions

© 2017 MuleSoft Inc. 109

Anypoint Platform Architecture Application Network Design

This approach, in the absence of an Enterprise Data Model, does not provide optimal isolation
from backend systems through the System API tier on its own. On the other hand,

• it is a pragmatic approach
• and further isolation occurs in the Process API tier

6.3.11. Designing Acme Insurance's System APIs

• Many System APIs sit infront of the Policy Admin System
◦ Defined by Bounded Contexts (motor, home) as well as by use cases (policy holder
search, option retrieval, etc.)
• The same principle applies to System APIs infront of the Motor Claims System and Home
Claims System
• All System APIs are JSON REST APIs and therefore define JSON data types in their RAML
definitions/libraries
◦ RAML actually allows the definition of data types that are representable in both XML and
JSON, so the data types in the RAML definitions of the System APIs need/should not be
JSON-specific
• No Enterprise Data Model is in use and hence, for instance, the representation of Motor
Policy returned by the "Motor Policy Search System API" is semantically equivalent to the
native data definition in the Policy Admin System with
◦ usage of JSON data types, JSON-compatible naming
◦ omitting fields not relevant for Motor Underwriting, which may well be contained in the
Mainframe-based database tables

See Figure 56.

6.4. Selecting API invocation patterns that address

NFRs

6.4.1. Asynchronously executing API invocations with polling

The "Submit auto claim" feature requires that the typically involved and lengthy execution of
submitting a claim is executed asynchronously, so that the Customer Self-Service Mobile App
is not blocked while claim submission occurs.

HTTP has native support for asynchronous processing of the work triggered by HTTP requests.
This feature is therefore immediately available to REST APIs (but not non-REST APIs like SOAP
APIs).

© 2017 MuleSoft Inc. 110

Anypoint Platform Architecture Application Network Design

API client API implementation

Initial request
1 HTTP PUT/POST/PATCH

2 validate request

alt [Invalid request]

3 HTTP 4xx client error
[Valid request]
HTTP 202 Accepted
4
Location: pollingURL

Polling
5 HTTP GET pollingURL

alt [Asynch processing ongoing]

6 HTTP 200 OK
[Asynch processing completed]
HTTP 303 See Other
7
Location: resultURL

Retrieve result
8 HTTP GET resultURL

HTTP 200 OK
9
body: result

API client API implementation

Figure 75. Asynchronous processing triggered by an API invocation from an API client to an
API implementation, with polling by the API client to retrieve the final result from the API
implementation

© 2017 MuleSoft Inc. 111

Anypoint Platform Architecture Application Network Design

1
The API client sends a HTTP request that will trigger asynchronous processing

2
The API implementation accepts the request and validates it

3
If the HTTP request is not valid then, as usual, a HTTP response with a HTTP 4xx client
error response code is returned

4
If HTTP request validation succeeds then the API implementation triggers asynchronous
processing (in the background) and returns a HTTP response with the HTTP 202 Accepted
response status code to the API client with a Location response header containing the URL
of a resource to poll for progress

5
The API client then regularly sends HTTP GET requests to the polling resource

6
The API implementation returns HTTP 200 OK if asynchronous process is still ongoing

7
but returns a HTTP response with HTTP 303 See Other redirect status response code and a
Location response header with the URL of a resource that gives access to the final result of
the asynchronous processing

8
The API client then sends a HTTP GET request to that last URL to retrieve the final result of
the now-completed asynchronous processing

The fact that HTTP-based asynchronous execution of API invocations is used should be
documented in the RAML definition of the respective APIs. In fact, the Acme Insurance C4E
has already published a resuable RAML library for this purpose: see Figure 74.

6.4.2. Asynchronously executing API invocations with callbacks

An alternative to the HTTP-supported polling-based async execution of API invocations is the
use of HTTP callbacks, aka webhooks. This requires the original API client to be reachable by
HTTP requests from the API implementation, and is therefore typically only available within
intranets.

© 2017 MuleSoft Inc. 112

Anypoint Platform Architecture Application Network Design

API client API implementation

Initial request
HTTP PUT/POST/PATCH
1
X-Callback-Location: callbackURL

2 validate request

alt [Invalid request]

3 HTTP 4xx client error
[Valid request]
HTTP 202 Accepted
4
X-Correlation-ID: correlationID

Deliver result
HTTP POST callbackURL
5 X-Correlation-ID: correlationID
body: result

6 HTTP 200 OK

API client API implementation

Figure 76. Asynchronous processing triggered by an API invocation from an API client to an
API implementation, with a callback from the API implementation to the API client to deliver
the final result. The callback URL is sent as a custom HTTP request header and the correlation
ID is also exchanged in a custom HTTP header

1
The API client sends a HTTP request that will trigger asynchronous processing

• With that HTTP request it sends the URL of a resource of the API client that will receive
callbacks
• The callback URL can be sent as a URL query parameter or custom HTTP request header

2
The API implementation accepts the request and validates it

3
If the HTTP request is not valid then, as usual, a HTTP response with a HTTP 4xx client

© 2017 MuleSoft Inc. 113

Anypoint Platform Architecture Application Network Design

error response code is returned

4
If HTTP request validation succeeds then the API implementation triggers asynchronous
processing (in the background) and returns a HTTP response with the HTTP 202 Accepted
response status code to the API client

• The HTTP response must also contain the correlation ID for the request, e.g., in a
custom response header

5
Once asynchronous processing is completed, the API implementation sends a HTTP POST
request to the callback URL containing the final result of the now-completed asynchronous
processing, sending the correlation ID (for instance) as a request header

6
The API client acknowledges receipt of the callback by returning a HTTP 200 OK from the
callback

The fact that HTTP-based asynchronous execution of API invocations is used should be
documented in the RAML definition of the respective APIs. The Acme Insurance C4E should
publish a resuable RAML library for this purpose.

6.4.3. Asynchronous API invocations for the "Submit auto

claim" feature
For the "Submit auto claim" feature, asynchronous API invocations are essential:

• Polling is used for the "Mobile Auto Claim Submission Experience API" because callbacks to
the Customer Self-Service Mobile App are impossible due to obvious networking
restrictions.
• The "Motor Claims Submission Process API", which is invoked by the "Mobile Auto Claim
Submission Experience API", can implement asynchronous processing via a callback, which
is more efficient than polling.

© 2017 MuleSoft Inc. 114

Anypoint Platform Architecture Application Network Design

Customer Self-Service Mobile Auto Claim Motor Claims

Mobile App Submission API Submission API

Initial request
1 HTTP POST

2 validate request

HTTP 202 Accepted

3
Location: pollingURL

Initial follow-on request

HTTP POST
4
X-Callback-Location: callbackURL

5 validate request

HTTP 202 Accepted

6
X-Correlation-ID: correlationID

Polling, asynch processing ongoing

7 HTTP GET pollingURL

8 HTTP 200 OK

Deliver follow-on result

HTTP POST callbackURL
9 X-Correlation-ID: correlationID
body: result

10 HTTP 200 OK

Polling, asynch processing completed

11 HTTP GET pollingURL

HTTP 303 See Other

12
Location: resultURL

Retrieve result
13 HTTP GET resultURL

HTTP 200 OK
14
body: result

Customer Self-Service Mobile Auto Claim Motor Claims

Mobile App Submission API Submission API

Figure 77. Asynchronous execution of the "Mobile Auto Claim Submission Experience API",
with polling from the Customer Self-Service Mobile App, feeding into asynchronous execution
of the "Motor Claims Submission Process API", with callback to the "Mobile Auto Claim
Submission Experience API"

© 2017 MuleSoft Inc. 115

Anypoint Platform Architecture Application Network Design

6.4.4. State handling for asynchronous execution of API

invocations
Whichever approach to asynchronously executing API invocations is used, it requires the API
implementation to maintain the state of each async invocation. It therefore makes API
implementations stateful.

Options for keeping state in API implementations implemented as Mule applications and
executing in a Mule runtime:

• an Object Store, a feature of the Mule runtime

• an external database

6.4.5. Exercise 9: Reflect on meaning and implications of

stateful API implementations
Asynchronous execution of claim submissions is the first example in our Enterprise
Architecture of stateful API implementations:

1. Discuss the exact meaning of "stateful API implementation"

2. Is statefulness of the API implementations of the "Mobile Auto Claim Submission Experience
API" and the "Motor Claims Submission Process API" avoidable?
3. List scenarios where statefulness makes a difference

Solution

6.4.6. Caching and safe HTTP methods

APIs use HTTP-based protocols: cached HTTP responses from previous HTTP requests may
potentially be returned if the same HTTP request is seen again.

Safe HTTP methods are ones that do not alter the state of the underlying resource. That is, the
HTTP responses to requests using safe HTTP methods may be cached.

The HTTP standard requires the following HTTP methods on any resource to be safe:

• GET
• HEAD
• OPTIONS

Safety must be honored by REST APIs (but not by non-REST APIs like SOAP APIs): It is the
responsibility of every API implementation to implement GET, HEAD or OPTIONS methods such

© 2017 MuleSoft Inc. 116

Anypoint Platform Architecture Application Network Design

that they never change the state of a resource.

6.4.7. Caching API invocations using HTTP facilities

Only safe API methods may return a cached HTTP response.

HTTP natively defines rigorous caching semantics using these (and more) HTTP headers. This
feature is therefore immediately available to REST APIs (but not non-REST APIs like SOAP
APIs):

• Cache-Control
• Last-Modified
• ETag
• If-Match, If-None-Match, If-Modified-Since
• Age

Caching requires

• storage management
• the manipulation of HTTP request and response headers in accordance with the HTTP
specification

Since HTTP-base caching is communicated by HTTP headers, it should be documented in the

RAML definition of each API. In particular, the C4E should define or reuse a RAML fragment to
be applied to cacheable API resources.

Figure 78. A cacheable RAML fragment published to the public Anypoint Exchange

Caching may occur

• in the API client

• in the API implementation
• in any network component, such as a caching proxy, between the API client and API
implementation

Mule applications acting as API clients or API implementations may make use of a caching
scope, which may be used, for instance, in a custom API policy, but Anypoint Platform as such

© 2017 MuleSoft Inc. 117

Anypoint Platform Architecture Application Network Design

contains no ready-made facilities for caching. Custom API policies for various caching
scenarios are available in the public Anypoint Exchange.

Figure 79. Custom API policies performing caching, published in the public Anypoint Exchange

6.4.8. Exercise 10: Identify interactions that would benefit from

caching
Investigate Acme Insurance’s application network and

1. Identify one API invocation that is cacheable (safe)

2. Specify whether caching is likely to benefit performance of that API invocation
3. Decide where caching is best performed: in the API client, the API implementation or in
between
4. Think about the criteria that should be applied to determine whether a cached HTTP
response may be returned

Solution

6.4.9. Retrying and idempotent HTTP methods

APIs use HTTP-based protocols: HTTP requests and responses may be lost due to a variety of
issues:

• A lost HTTP request should be retried

• A lost HTTP response may cause duplicate processing if the HTTP request is retried

Idempotent HTTP methods are ones where a HTTP request may be re-sent without causing
duplicate processing. That is, idempotent HTTP methods may be retried.

The HTTP standard requires the following HTTP methods on any resource to be idempotent.

© 2017 MuleSoft Inc. 118

Anypoint Platform Architecture Application Network Design

• GET
• HEAD
• OPTIONS
• PUT
• DELETE

Of these methods, only PUT and DELETE may change the state of a resource (i.e., are not
safe). On the other hand, POST and PATCH are not idempotent (and not safe): if a HTTP
response is lost the HTTP request can, in general, not be re-sent without causing duplicate
processing.

Idempotency must be honored by REST APIs (but not by non-REST APIs like SOAP APIs): It is
the responsibility of every API implementation to implement PUT and DELETE methods such
that they never perform an action if the PUT or DELETE was already successfully processed.

Mule applications acting as API implementations may make use of an idempotent-message-

filter to aid the implementation of this requirement.

How does an API implementation decide if a HTTP request was already received and must
therefore be disregarded (if it is a PUT or DELETE)?

• One approach is to treat all requests with identical "content" (HTTP request body and
relevant request headers) as identical. This is similar to the default implementation of the
idempotent-message-filter (which makes that decision based on a hash of the Mule
message body). However, this approach prohibits identical PUT or DELETE requests from
being processed at all, which may be problematic.
• A common refinement of this approach is therefore to require the API client to generate a
unique request ID and add that to the HTTP request. If the API client re-sends a request it
must use the same request ID as in the original request. It follows that the content of
requests of this kind can only be identical if the request ID is also identical, so that identical
requests can be determined by the API implementation simply by comparing request IDs.
The idempotent-message-filter can easily be configured to do that.

6.4.10. HTTP-based optimistic concurrency control

In some cases the updates to resources must be serialized, so that concurrent updates to the
resource do not result in previous changes being overwritten without warning.

HTTP supports optimistic concurrency control of this kind natively with the combination of the
following facilities. This feature is therefore immediately available to REST APIs (but not non-
REST APIs like SOAP APIs):

© 2017 MuleSoft Inc. 119

Anypoint Platform Architecture Application Network Design

• the ETag HTTP response header to send a resource version ID in the HTTP response from
the API implementation to the API client
• the If-Match HTTP request header to send the resource version ID on which an update is
based in an HTTP PUT/POST/PATCH request from API client to API implementation
• the HTTP 412 Precondition Failed client error response code to inform the API client that the
resource version ID it sent was stale and hence the requested change not performed
• the HTTP 428 Precondition Required client error response code to inform the API client that
the resource in question is protected against concurrent modification and hence requires
If-Match HTTP request headers, which were however missing from the HTTP request

Because usage of these headers changes the technology interface of the API, this should be
fully documented in the RAML definition of each API that uses optimistic concurrency. A RAML
fragment in the form of a trait should be used to capture this element of the contract
between API client and API. This RAML fragment is reusable and should be made available as a
Anypoint Design Center project and published to Anypoint Exchange.

© 2017 MuleSoft Inc. 120

Anypoint Platform Architecture Application Network Design

API client 1 API client 2 API implementation

Retrieve current resource state

1 HTTP GET

HTTP 200 OK
2
ETag: v42

3 HTTP GET

HTTP 200 OK
4
ETag: v42

Failed resource modification without If-Match header

5 HTTP PUT/POST/PATCH

6 HTTP 428 Precondition Required

Successful resource modification

HTTP PUT/POST/PATCH
7 If-Match: v42
body: new resource state

HTTP 200 OK
8
ETag: v43

Failed resource modification based on stale version

HTTP PUT/POST/PATCH
9 If-Match: v42
body: outdated resource state

HTTP 412 Precondition Failed

10
ETag: v43

API client 1 API client 2 API implementation

Figure 80. Optimistic concurrency preventing concurrent modification of a REST API resource

6.4.11. Exercise 11: Identify API resources that may require

protection from concurrent modification
Inspect all APIs in Acme Insurance’s application network and

© 2017 MuleSoft Inc. 121

Anypoint Platform Architecture Application Network Design

1. Identify resources accessed by those APIs that may require protection from concurrent
modification.
2. Discuss what implementing concurrent modification protection in these APIs would mean
for their API clients.
3. Do you consider HTTP-based optimistic concurrency control a standard feature of APIs that
is helpful in many situations?

Solution

The features discussed so far do neither require nor benefit from optimistic concurrency
control:

• "Create quote for aggregators" feature is not a modification but a de-novo creation of new
quotes
• "Retrieve policy holder summary" feature is a read-only operation
• "Submit auto claim" feature is not a modification but a de-novo creation of a new claim
submission

A hypothetical feature that might benefit from optimistic concurrency control is the
modification of policy holder details through the Customer Self-Service Mobile App:

• It is theoretically conceivable that updates to the details of the same policy holder occur
concurrently, through separate session of the Customer Self-Service Mobile App or through
the Customer Self-Service Mobile App and a backend system.
• But this is unlikely, and even if it happened there is no clear business need or value in
protecting against this kind of situation.

This discussion shows that HTTP-based optimistic concurrency control to achieve protection of
API resources from concurrent modification is a technical approach that is to be used with
caution and only when there is clear business value in doing so. Most often, the nature of the
interactions in an application network calls for embracing concurrency rather than imposing
the illusion that all modifications to resources occur sequentially along one universally
applicable time axis.

6.5. Taking stock

6.5.1. Reviewing the current state of Acme Insurance's

application network
At this point you have

© 2017 MuleSoft Inc. 122

Anypoint Platform Architecture Application Network Design

• identified all APIs

• for both products/projects currently in-scope

In collaboration with the C4E you have selected an enterprise-wide (application network-wide)
approach to

• API versioning
• API data model design (no Enterprise Data Model)

For each API you have

• captured NFRs
• decided on architecturally relevant design aspects (such as caching, asynchronous
execution and concurrency handling)
• selected and configured appropriate API policies

Along the way, important Technology Architecture-aspects of the Enterprise Architecture have
been decided:

• Anypoint Platform and CloudHub have been chosen and configured to support the APIs and
their API policies
◦ For instance, Amazon Web Services VPCs have been set up and CloudHub dedicated
load-balancers configured for TLS mutual authentication
• API policies are being enforced in the API implementations themselves rather than in API
proxies
• An Identity Provider (PingFederate) has been chosen for OAuth 2.0 Client Management

Last but not least, a decentralized C4E has been established at Acme Insurance IT, which

• enables the LoB IT project teams to implement the strategic products "Aggregator
Integration" product and "Customer Self-Service App" product
• owns the harvesting and publishing of reusable assets into Acme Insurance’s Anypoint
Exchange
• helps setting and spreading the aforementioned application network-wide standards

All but one API, namely the "Aggregator Quote Creation Experience API", whose technology
interface is defined by the Aggregator, are JSON REST APIs.

Almost all of the above information is directly visible in the interface contract of APIs and has
therefore been defined in RAML fragments and RAML definitions.

© 2017 MuleSoft Inc. 123

Anypoint Platform Architecture Application Network Design

The API Portal of each API augments the "raw" RAML definition with an API Notebook, an API
Console and essential textual descriptions and context-setting.

All of the above information has been published to Acme Insurance’s Anypoint Exchange and is
visible across the Acme Insurance application network.

Summary
• In designing APIs start with the RAML definitions, using the simulation features of API
designer
• Extract reusable RAML fragments and publish them to Anypoint Exchange
• A semantic versioning-based API versioning strategy was chosen, that exposes only major
version numbers in all places except Anypoint Exchange
• API data models were defined by the Bounded Context to which the APIs belong
• System APIs were chosen to abstract only slightly from backend systems
• HTTP-based asynchronous execution of API invocations and caching were employed
wherever needed to meet NFRs
• Most decisions change the interface contract of APIs and were captured in RAML fragments
and RAML definitions and published to Anypoint Exchange

© 2017 MuleSoft Inc. 124

Anypoint Platform Architecture Application Network Design

Chapter 7. Architecting and Deploying Effective

API Implementations

Objectives
• Know about auto-discovery of API implementations implemented as Mule applications
• Appreciate how Anypoint Connectors serve System APIs in particular
• Understand CloudHub
• Apply strategies that help API clients guard against failures in API invocations
• Understand the role of CQRS and the separation of commands and queries in API-led
connectivity
• Know the role of Event Sourcing

7.1. Developing API implementations for Mule runtimes

and deploying them to CloudHub

7.1.1. Introducing API implementations management on

Anypoint Platform
API implementations may be

• Either developed for the Mule runtime

◦ in Anypoint Studio or Flow designer
◦ and deployed to Mule runtimes, e.g., MuleSoft-managed and -hosted in CloudHub
◦ with API Management and Analytics provided by Anypoint Platform with or without
separate API proxies
• Or developed for other runtimes (Node.js, Spring Boot, etc.)
◦ and deployed to matching runtimes outside Anypoint Platform
◦ with API Management and Analytics provided by Anypoint Platform via API proxies

7.1.2. Introducing Auto-discovery of API implementations

API implementations developed as Mule applications and deployed to a Mule runtime should be
configured to participate in auto-discovery:

• When the API implementation starts up it automatically registers with Anypoint API
Manager as an implementation of a given API version

© 2017 MuleSoft Inc. 125

Anypoint Platform Architecture Application Network Design

• and receives all API policies configured for that API version
• The API implementation should be configured to refuse API invocations until all API policies
have been applied
◦ This is called the gatekeeper feature of the Mule runtime

The above suggests that auto-discovery is a form of auto-registration of an API

implementation with Anypoint API Manager.

7.1.3. Anypoint Connectors to implement System APIs

Acme Insurance has extensive need to connect to backend systems. By definition, this mostly
concerns the API implementations of System APIs:

• The Mainframe-based Policy Admin System, which needs to be accessed via WebSphere MQ
• The WebSphere-deployed Motor Claims System, which needs to be integrated with by
directly accessing its DB/2 database
• The web-based Home Claims System, which exposes SOAP APIs

See Figure 56.

Connectors are either pre-built (Anypoint Connectors) or custom-developed components that

help integrate Mule applications with external systems:

• Anypoint Platform has over 120 Anypoint Connectors

◦ approx. 30 of which are bundled with Anypoint Studio
◦ while others are available in the public Anypoint Exchange and the MuleSoft Nexus
Maven repository
• Support categories: Premium, Select, MuleSoft Certified, Community

Also see Figure 22.

Acme Insurance can use the following Anypoint Connectors to implement its System APIs:

• The WMQ Connector to connect to WebSphere MQ (https://docs.mulesoft.com/mule-user-

guide/v/3.8/wmq-connector)
• The Database Connector to access the DB/2 database (https://docs.mulesoft.com/mule-
user-guide/v/3.8/database-connector)
• The Web Service Consumer to invoke SOAP APIs (https://docs.mulesoft.com/mule-user-
guide/v/3.8/web-service-consumer)

See https://docs.mulesoft.com/mule-user-guide/v/3.8/anypoint-connectors for documentation

© 2017 MuleSoft Inc. 126

Anypoint Platform Architecture Application Network Design

on the more popular Anypoint Connectors.

The existence of Anypoint Connectors is one more reason why Acme Insurance elects to
implement API implementations for the Mule runtime, using Anypoint Studio.

7.1.4. Understanding CloudHub

CloudHub provides a scalable, performant and highly-available option for executing API
implementations in the form of Mule applications on Mule runtime instances:

• CloudHub and API implementations deployed to CloudHub execute on Amazon Web Services
infrastructure
• Every API implementation is assigned a DNS name that resolves to the CloudHub Load
Balancer
◦ CloudHub workers deployed to CloudHub’s shared worker cloud are exposed only via the
public CloudHub Load Balancer, which builds on top of the Amazon Web Services Elastic
Load Balancer (ELB)
◦ CloudHub workers deployed to a VPC can also use CloudHub Dedicated Load Balancers,
which currently do not utilize the ELB
• Plus every API implementation also receives two other well-known DNS names,
◦ one maps to the public IP addresses of all CloudHub workers of the API implementation
◦ the other maps to the internal IP addresses of all CloudHub workers of the API
implementation for use within a VPC
◦ CloudHub Dedicated Load Balancers allow the load balancer to be configured with client
certificates in order to perform TLS mutual authentication
◦ DNS entries are maintained by the Amazon Web Services platform service Route 53
• HTTP and HTTPS requests, i.e., API invocations, sent by the API client to the CloudHub Load
Balancer on port 80 and 443, respectively, are forward by the load balancer to one of the
API implementation’s CloudHub workers, where they reach the API implementation Mule
application at port 8081 and 8082, respectively
◦ HTTP and HTTPS requests bypassing the CloudHub Load Balancer, i.e. being sent to the
public IP addresses of the API implementation’s CloudHub workers, do not undergo this
port change
◦ HTTP and HTTPS requests to the internal IP addresses of CloudHub workers, from within
the VPC, by convention go to ports 8091 and 8092, respectively
• CloudHub workers are Amazon Web Services EC2 instances running Linux, and a Mule
runtime within a JVM
• The maximum number of CloudHub workers for a single API implementation is currently 8

© 2017 MuleSoft Inc. 127

Anypoint Platform Architecture Application Network Design

• CloudHub workers also execute CloudHub system services on the OS and Mule runtime
level which are required for the platform capabilities provided by CloudHub, such as
◦ Monitoring of API implementations in terms of CPU/memory/etc. usage, number of
messages and errors, etc., which allows Anypoint Platform to provide alerts based on
these metrics
◦ Auto-restarting failed CloudHub workers (including a failed Mule runtime on an otherwise
functional EC2 instance)
◦ Load-balancing via the CloudHub Load Balancer only to healthy CloudHub workers
◦ Provisioning of new CloudHub workers to increase/reduce capacity
◦ Persistence of Object Stores, message payloads, etc. across the CloudHub workers of an
API implementation
◦ DNS of the CloudHub workers and the CloudHub Load Balancer, as described above
• The API implementation implemented as a Mule application, in collaboration with the Mule
runtime, confers the capability of invoking backend systems and APIs

Table 2. CloudHub worker sizing and illustratory mapping to EC2 instance types.
Worker Name Worker Memory Worker Storage EC2 Instance EC2 Instance
Name Memory
0.1 vCores 500 MB 8 GB t2.micro 1 GB
0.2 vCores 1 GB 8 GB t2.small 2 GB
1 vCores 1.5 GB 8 + 4 GB m3.medium 3.75 GB
2 vCores 3.5 GB 8 + 32 GB m3.large 7.5 GB
4 vCores 7.5 GB 8 + 40 + 40 GB m3.xlarge 15 GB
8 vCores 15 GB 8 + 40+ + 40+ m3.2xlarge 30 GB
GB
16 vCores 32 GB 8 + 40+ + 40+ m4.4xlarge 64 GB
GB

© 2017 MuleSoft Inc. 128

Anypoint Platform Architecture Application Network Design

API client

DNS lookup
Client certificates Amazon
Route 53
HTTP/S

optional

Amazon ELB

HTTP/S HTTP/S

HTTP/S HTTP/S

CloudHub Worker 1 CloudHub Worker n

API API
implementation implementation

Figure 81. A very simple depiction of the general high-level CloudHub Technology Architecture
as it serves API clients invoking APIs exposed by API implementations implemented as Mule
applications running on CloudHub

Monitoring and
Alerting of API CloudHub Worker
Implementations
CloudHub system services Policy Holder Search
Implementation
HA and Scalable
Execution
Mule runtime Policy Holder Search
RAML Definition
healthchecks
Linux
Persistence Provisioning Load- Auto-restart
balancing

AWS Platform Backend System Fault-Tolerant API

Naming
Services Integration Invocation

Figure 82. Anatomy of a CloudHub worker used by the API implementation of the "Policy
Holder Search Process API" and the capabilities bestowed on the API implementation by the
CloudHub worker, also by making use of the Amazon Web Services Platform Services

7.2. Designing API clients to use fault-tolerant API

invocations

© 2017 MuleSoft Inc. 129

Anypoint Platform Architecture Application Network Design

7.2.1. Exercise 12: Failures in API invocations

1. List every kind of failure that can occur when an API client invokes an API implementation
2. Think of ways of guarding against each of these failures.

Solution

The invocation of an API implementation by an API client fails if any of the intervening
components fails at the moment of the API invocation:

• The hardware on which the API client or API implementation execute

• The virtualization or container stacks in which the API client or API implementation execute
• The operating system, JVM or other runtime and libraries on which the API client or API
implementation rely
• Any network component such as Ethernet cards, switches, routers, cables, WIFI
transmitters, …
• This includes all Anypoint Platform components and underlying Amazon Web Services
services involved in the API invocation: API policies, API proxies, load balancers, CloudHub
workers, etc.
• The API implementation itself, e.g., because of a bug in the application code or a failed
deployment

7.2.2. Understanding the significance of failure in application

networks
The impact of failed API invocations is amplified by the typically high degree of dependency of
any API implementation on other APIs. This high degree of dependency of APIs is an inherent
feature of application networks. It is also typically a desired feature of application networks
because it is one direct consequence of a high degree of reuse of APIs within the application
network, and as such is proof of the success of the application network.

Expressed in graph theoretic terms, the min/max/average degree of a graph of APIs is the
min/max/average number of API implementations that depend on any given API. In this
sense, successful application networks are characterized by a high (average) degree.

However, a high degree of dependency between APIs means that a failures in the invocation of
an API affects many other API implementations and the services they offer to the application
network - which in turn affects many other API implementations and their services - and so
on. That is, if unchecked, failures in API invocations propagate transitively through an
application network.

© 2017 MuleSoft Inc. 130

Anypoint Platform Architecture Application Network Design

In other words, a successful application network - one with a high degree of dependency
between its APIs - is also an application network in which the failure of any API triggers
downstream failures of many other APIs.

For this reason, making API invocations fault-tolerant is an essential aspect of successful
application networks.

7.2.3. Designing API clients for fault-tolerant API invocations

A fault-tolerant API invocation is an invocation from an API client to an API implementation via
its API where a failure of the API invocation does not necessarily lead to a failure of the API
client. Because the API client is typically itself an API implementation, this means that the API
provided by that API implementation does not in turn cause its API clients to experience
failures.

The most important goal of making API invocations fault-tolerant is breaking transitive failure
propagation.

Upstream API API, API Client Downstream

Client using fault- API, failing
Succeeding API invocation tolerant API Failing API invocation
invocation
strategies

Figure 83. Visualization of an API client that itself exposes an API to upstream API clients and
which employs fault-tolerant API invocations to a downstream API

There is a fairly well-established repertoire of approaches for implementing fault-tolerant

invocations of any kind. Most of these strategies should be applied by all API clients to all API
invocations whenever possible:

• Timeout
• Retry
• Circuit Breaker
• Fallback API invocation
• Opportunistic parallel API invocations
• Cached fallback result
• Static fallback result

Also see [Ref11], [Ref12].

© 2017 MuleSoft Inc. 131

Anypoint Platform Architecture Application Network Design

2x timeout
Upstream API API, API Client Primary
Client using fault- 1. Downstream
Succeeding API invocation tolerant API Failing API invocation API, failing
invocation
strategies 2.

4. 3.
Fallback API invocation
Retrieve Lookup
2x timeout
Fallback
Downstream
Static Results Client-Side Cache API

Figure 84. The most important fault-tolerant API invocation strategies and the order in which
they should be employed

7.2.4. Using timeouts to guard against slow APIs

When the invocation of a downstream API is slow to return

• the SLA of the API client is put at risk even if the API invocation ultimately succeeds
• the API invocation has a higher-than-usual probability of eventually failing anyways

For both of these reasons, timeouts for API invocations should be set carefully to

• be in accordance with the SLA of the API client

• be as low as possible, given the SLA-defined expected response time of the API

timeout
Upstream API API, API Client Primary
Client using fault- Downstream
Succeeding API invocation tolerant API Failing API invocation API, failing
invocation
strategies

Figure 85. Short timeouts of API invocations are the most fundamental protection against
failing APIs

For instance:

• The "Aggregator Quote Creation Experience API" has an SLA (defined by the NFRs for the
"Create quote for aggregators" feature) of a median/max response time of 200 ms/500 ms
• It synchronously invokes 3 Process APIs, in turn, starting with "Policy Holder Search
Process API"
• The task performed by the "Policy Holder Search Process API" is the simplest of all 3
Process APIs and should hence be fastest to accomplish
• Hence the "Aggregator Quote Creation Experience API" should define a timeout of no more
than approx. 100 ms for the invocation of the "Policy Holder Search Process API"

© 2017 MuleSoft Inc. 132

Anypoint Platform Architecture Application Network Design

• The SLA for the "Policy Holder Search Process API" must therefore guarantee/promise that
a sufficient percentage (say, 95%) of API invocations will complete within 100 ms. If "Policy
Holder Search Process API"'s SLA does not live up to this, then this API (or better, its
current API implementation) is unsuitable for implementing the "Aggregator Quote Creation
Experience API". For instance, if the percentage of API invocations to the "Policy Holder
Search Process API" that can be expected to complete within the timeout of 100 ms is
significantly below 95% (say, 80%) then, under normal conditions (without failure) the
percentage of these API invocations that will be timed-out is unreasonably high (20%) and
will therefore jeopardize the effiicent operation of the "Aggregator Quote Creation
Experience API". (Response times are typically log-normally distributed.)

A timed-out API invocation is equivalent to a failed API invocation, hence timing-out can only
be the first in a sequence of fault-tolerance strategies.

API clients implemented as Mule applications and executing on a Mule runtime have various
options for configuring timeouts of API invocations:

• At the level of the HTTP request

• For an entire transaction
• As part of higher-level control constructs like Scatter-Gather

7.2.5. Retrying failed API invocations

After an API invocation has failed it may succeed when tried again. This will only be the case if
the failure was transient rather than permanent. This is, retrying an API invocation is wasteful
if the API invocation failure is of a permanent nature.

It is typically difficult for an API client to decide beyond doubt that a failure which occurred
during an API invocation was of a transient nature. This is way the default approach is often to
retry all failed API invocations.

In general, all connection issues (which materialize in Mule runtime as Java net or IO
exceptions) should be dealt with as transient failures.

In REST APIs, which are assumed to make correct use of HTTP response codes, response
codes in the 4xx range signify client errors and are therefore mostly permanent and the API
invocation that led to such a response code should hence not be retried. HTTP response codes
in the 5xx range, by contrast, should be expected to signify transient failures. These HTTP 4xx
client error response codes are exceptions to the previous rule and should also be treated as
transient failures:

• HTTP 408 Request Timeout

© 2017 MuleSoft Inc. 133

Anypoint Platform Architecture Application Network Design

• HTTP 423 Locked

• HTTP 429 Too Many Requests

In addition, HTTP states that only idempotent HTTP methods (see Section 6.4.9) may be
retried without causing potentially unwanted duplicate processing:

• GET
• HEAD
• OPTIONS
• PUT
• DELETE

Retrying an API invocation by necessity increases the overall processing time for the API client.
It should therefore be

• restricted to only a few retries

• with short wait times between retries
• combined with short timeouts for each API invocation

2x timeout
Upstream API API, API Client Primary
Client using fault- Downstream
Succeeding API invocation tolerant API Failing API invocation API, failing
invocation
strategies

Figure 86. Retrying API invocations a few times with short delays between retries and short
timeouts for each API invocation

API clients implemented as Mule applications and executing on a Mule runtime have the HTTP
Request Connector and Until Successful Scope at their disposal for configuring retries of API
invocations. The HTTP Request Connector has (configurable) support for interpreting certain
HTTP response status codes as failures.

7.2.6. Invoking failing APIs less often with Circuit Breakers

An API implementation that fails, maybe due to a failing downstream system, may need time
to recover. This recovery process may actually be slowed-down by insistent API clients that
continue invoking the API exposed by that API implementation - only to receive failures in
return.

A Circuit Breaker

© 2017 MuleSoft Inc. 134

Anypoint Platform Architecture Application Network Design

1. monitors API invocations

2. after a certain number (or percentage) of failed invocations of an API "opens the circuit"
3. while in the "open" state immediately fails invocations of that API to the API client without
even invoking the API itself, thereby giving the underlying API implementation time to heal
4. after a certain time gently begins passing API invocations through to the API ("half-opening
the circuit")
a. immediately transitioning back to the "open" state upon an API invocation failure,
because this indicates that the API implementation is not yet ready to handle API
invocations
b. while "closing the circuit" if API invocations are sufficiently successful, because this
indicates that the API implementation has recovered.

Seen from an API client, the most important contribution of a Circuit Breaker is that, when it is
in the "open" state, it saves the API client the wasted time and effort of invoking a failing API.
Instead, thanks to the Circuit Breaker, these invocations fail immediately and the API client
can quickly move on to apply fallback strategies as discussed in the remainder of this section.

A Circuit Breaker is by definition a stateful component, i.e., it monitors and manages API
invocations over "all" API clients. The scope of "all" may vary:

• In the easiest case, all API invocations from within a single instance of a type of API client
are managed
◦ E.g., all API invocations from the API client executing in a single CloudHub worker are
managed together
◦ This means that the different instances of the API client executing in different CloudHub
workers keep distinct statistics and state for the invocations of the failing API
• Alternatively, all API invocations from all instances of a type of API client are managed
together
◦ E.g., all API invocations from all instances of the API client executing in all CloudHub
workers are managed together
◦ This means that the different instances of the API client executing in different CloudHub
workers all share the same statistics and state for the invocations of the failing API
◦ Requires remote communication between instances of the API client, e.g., via a Mule
runtime Object Store
• In the extreme case, all API invocations from all types of API clients are managed together
◦ E.g., all API invocations from all instances of any API client executing in any CloudHub
worker are managed together
◦ This means that the different instances of any API client executing in any CloudHub

© 2017 MuleSoft Inc. 135

Anypoint Platform Architecture Application Network Design

workers all share the same statistics and state for the invocations of the failing API
◦ Typically requires the Circuit Breaker to be an application network-wide shared resource,
e.g., an API in its own right

API clients implemented as Mule applications and executing on a Mule runtime have open-
source implementations of the Circuit Breaker pattern at their disposal for the configuration of
API invocations.

7.2.7. Invoking a fallback API

When an API invocation fails, even after a reasonable number of retries, it may be possible to
invoke a different API as a fallback.

For instance, when the API implementation of the "Policy Holder Search Process API" has
definitely failed invoking the "Motor Policy Holder Search System API", it may instead invoke a
fallback API that is sufficient, if not ideal, for its purposes. (A fallback API by definition is never
ideal for the purposes of the API client at hand - otherwise it would be its primary API.)

This fallback API

• could be an old, deprecated version of the same API, that may however still be available;
e.g., an old but sufficiently compatible version of the "Motor Policy Holder Search System
API"
• could be an alternative endpoint of the same API and version; e.g., an endpoint of the
"Motor Policy Holder Search System API" from the DR site
• could be an API that does more than is required, and is therefore not as performant as the
primary API; e.g., the "Motor Policy Search System API" may provide the option to search
the Policy Admin System for Motor Policies by the name of the policy holder, similar to the
input received by the "Motor Policy Holder Search System API", returning entire Motor
Policies, from which the motor policy holders actually needed by the "Policy Holder Search
Process API" (the API client of the "Motor Policy Holder Search System API") can be
extracted
• could be an API that does less than is required, therefore forcing the API client into offering
a degraded service - which is still better than no service at all

© 2017 MuleSoft Inc. 136

Anypoint Platform Architecture Application Network Design

2x timeout
Upstream API API, API Client Primary
Client using fault- Downstream
Succeeding API invocation tolerant API Failing API invocation API, failing
invocation
strategies

Fallback API invocation

2x timeout
Fallback
Downstream
API

Figure 87. After retries on the primary API have been exhausted, at least one fallback API
should be invoked, even if that API is not a full substitute for the primary API

API clients implemented as Mule applications and executing on a Mule runtime have the Until
Successful Scope and exception strategies at their disposal, which together allow for
configuring fallback actions such as the fallback API invocations.

7.2.8. Opportunistically invoking APIs in parallel

If

• the possibility of a failure in an API invocation is considered generally high

• and/or the API client performing the API invocation is particularly important
• and a fallback API as discussed previously is available

then the invocation of the primary API and the fallback API may be performed in parallel. If
the primary API does not respond in time (i.e., a short time-out should be used) and the
fallback API has delivered a result, then the result from the fallback API invocation is used.
Overall then, little time has been lost because the two API invocation were performed in
parallel rather than serially.

This is an opportunistic, egotistical strategy that puts increased load on the application
network by essentially doubling the number of API invocation for the cases where this strategy
is used. As thus it should be used only in exceptional cases as indicated above.

7.2.9. Using a previously cached result as a fallback

After retries of an API invocation are exhausted and a fallback API has also failed or is not
available, a result from a previous API invocation may be used instead. In other words, the API
client needs to implement some form of client-side caching, where the results of API
invocations are preserved indexed by the input to those API invocations. An API invocation
result can then be looked up in the cache by the input to the API invocation that has just
failed.

© 2017 MuleSoft Inc. 137

Anypoint Platform Architecture Application Network Design

Client-side caching is governed by the same rules as general caching in an HTTP setting - it’s
just performed within the API client rather than by a API implementation or an intervening
network component.

In particular, only results from safe HTTP methods (see Section 6.4.6) should be cached:

• GET
• HEAD
• OPTIONS

and HTTP caching semantics should be honored (see Section 6.4.7). Although, in practice, it
would typically still be preferable to use an outdated/stale cached HTTP response, thereby
effectively ignoring HTTP caching semantics and control headers, than to not recover from the
failed API invocation.

2x timeout
Upstream API API, API Client Primary
Client using fault- Downstream
Succeeding API invocation tolerant API Failing API invocation API, failing
invocation
strategies

Lookup

Client-Side Cache

Figure 88. Using an API invocation result cached in the API client as a fallback for failing API
invocations

For instance,

• if the API implementation of the "Policy Options Ranking Process API" performs client-side
caching of its invocations of the "Policy Options Retrieval System API"
• and API invocations of the "Policy Options Retrieval System API" currently fail
• then the "Policy Options Ranking Process API" API implementation may use the cached
response from a previous, matching request to the "Policy Options Retrieval System API"

Caching increases the memory footprint of the API client, e.g. the API implementation of the
"Policy Options Ranking Process API". It also adds processing overhead for populating the
cache after every successful API invocation. There is furthermore the question of the scope of
caching, similar to the state handling discussed in Section 7.2.6.

API clients implemented as Mule applications and executing on a Mule runtime have the Cache
Scope and Object Store Connector available, which both support client-side caching.

© 2017 MuleSoft Inc. 138

Anypoint Platform Architecture Application Network Design

7.2.10. Using a static fallback result

After all previously discussed options for recovering from a failing API invocation have failed,
too, a prepared static result may be used instead of the result expected from the API
invocation.

Typically this works best for APIs that return results akin to reference data, e.g.,

• countries
• states
• currencies
• products

2x timeout
Upstream API API, API Client Primary
Client using fault- Downstream
Succeeding API invocation tolerant API Failing API invocation API, failing
invocation
strategies

Retrieve

Static Results

Figure 89. Using statically configured API invocation results as fallback for failing API
invocations

For instance, when the API implementation of the "Policy Options Ranking Process API" fails to
invoke the "Policy Options Retrieval System API", it may be able to work with a list of common
policy options loaded from a configuration file. These policy options may be limited, and may
not be ideal for creating the best possible quote for the customer, but it may be better than
not creating a quote at all. Again, the principle is to prefer a degraded service to no service at
all.

API clients implemented as Mule applications and executing on a Mule runtime have many
options available for storing and loading static results. One such option is to use properties,
which, when the Mule application is deployed to CloudHub, can actually be updated via the
Anypoint Runtime Manager web UI.

7.3. Understanding architecturally significant

persistence choices for API implementations

© 2017 MuleSoft Inc. 139

Anypoint Platform Architecture Application Network Design

7.3.1. Introducing CQRS as an API implementation strategy

See the corresponding glossary entry.

Characteristics of CQRS:

• Allows reads and writes to be optimized and scaled independently

• Allows the choice of independent persistence mechanisms for reads and writes
• Commands are formulated in the domain language of the Bounded Context and trigger
writes
• Commands are typically queued and executed asynchronously
• Queries are optimized for the API clients' needs and execute synchronously
• Because queries operate against a distinct data store they may return slightly out-of-date
data
• Complicates the architecture, design and implementation of an API implementation and
filters through to the API itself

CQRS is a design choice to be made independently for each API implementation, but it is
architecturally significant because

• it causes eventual consistency between read-sides and write-sides

• it is typically apparent in the API specification of the API exposed by the API
implementation
◦ It may also cause an API to be split into one API for queries and another API for
commands

The option to select persistence mechanisms independently for the read-side and write-side of
an API implementation may manifest itself in choosing entirely different persistence
technologies - e.g., a denormalized NoSQL database for the read-side and a fully normalized
relational database schema for the write-side. But it may equally just mean storing read-side
and write-side data in different table spaces in the same RDBMS, potentiall with less
normalization and fewer database constraints on the read-side.

7.3.2. Viewing Acme Insurance's application network from a

CQRS perspective
At Acme Insurance a separation between commands and queries has emerged naturally:

• The "Motor Claims Submission Process API" and "Motor Claims Submission System API"
accept commands in the form of claim submissions, which are executed asynchronously

© 2017 MuleSoft Inc. 140

Anypoint Platform Architecture Application Network Design

• The "Claims Process API" provides synchronous queries against claims, including ones that
result from previous claim submissions
• Read-side and write-side persistence in this case are both hidden inside the Motor Claims
System, which may, but typically will not, use different persistence mechanisms for the two
cases
◦ But on the level of the APIs there is clear CQRS-style separation
◦ This is a typical situation in integration solutions where the imperative of reusing existing
systems results in technologically and stylistically more muddled architectures than
would be the case in greenfield application development

Claims Query Claim Submission

Command

Process APIs

Claims API Motor Claims

Submission API

System APIs

Motor Claims Motor Claims

Search API Submission API

Motor Claims
System

Figure 90. CQRS emerging naturally on the API-level through the "Motor Claims Submission
Process API" and "Motor Claims Submission System API" accepting commands and the "Claims
Process API" accepting queries, though persistence is encapsulated in the shared Motor Claims
System

7.3.3. Introducing persistence with Event Sourcing

See the corresponding glossary entry.

Event Sourcing is very similar in spirit to database transaction logs. The important difference is
that Event Sourcing is an approach at the application layer, chosen by application components
and API implementations, rather than hidden behind the technology service offered by a
RDBMS.

Characteristics of Event Sourcing:

• Events are expressed in the domain language of the Bounded Context

© 2017 MuleSoft Inc. 141

Anypoint Platform Architecture Application Network Design

• Events typically arise directly from executing CQRS-style commands

• If CQRS is used then events are typically used to propagate state changes from the write-
side to the read-side
◦ This often relies on messaging systems like Anypoint MQ to propagate events
asynchronously
• A typical performance optimization is to accumulate events into a snapshot state at regular
intervals

Unlike CQRS, Event Sourcing by itself is invisible in the API specification of the API exposed by
an API implementation. It is therefore an implementation-level design decision.

Summary
• API implementations can target the Mule runtime or other runtimes while still being
managed by Anypoint Platform
• API implementations implemented as Mule applications can be automatically discovered by
Anypoint Platform
• Anypoint Platform has over 120 Anypoint Connectors, which are indispensable for
implementing System APIs
• CloudHub is an Amazon Web Services-based PaaS for the scalable, performant and highly-
available deployment of Mule applications
• API clients, in particular those which are in turn API implementations, must employ
strategies to guard against failures in API invocations
◦ E.g., Retry, Circuit Breaker, Fallbacks
• Some API implementations may benefit from using CQRS as a persistence strategy, which
in turn influences the design of their API
• Separation of commands and queries often arises naturally in API design, even in the
absence of true CQRS
• Event Sourcing is an implementation-level design decision of each API implementation

© 2017 MuleSoft Inc. 142

Anypoint Platform Architecture Application Network Design

Chapter 8. Augmenting API-Led Connectivity

With Elements From Event-Driven Architecture

Objectives
• Know when to make use of elements of Event-Driven Architecture in addition to API-led
connectivity
• Understand events and message destinations
• Impose event exchange patterns in accordance with API-led connectivity
• Get to know Anypoint MQ
• Apply Event-Driven Architecture with Anypoint MQ to address NFRs of the "Customer Self-
Service App" product

8.1. Choosing Event-Driven Architecture to meet some

NFRs of the "Customer Self-Service App" product

8.1.1. Revisiting the NFRs for the "Customer Self-Service App"

product
The "Customer Self-Service App" product requires that claim submissions made from the
Customer Self-Service Mobile App shall be visible immediately through that app, even though
the Motor Claims System does not give access to newly submitted claims until they have
passed a lengthy verification phase. In other words, claim submission made via the "Submit
auto claim" feature should be reflected sooner via the "Retrieve policy holder summary"
feature than the Motor Claims System gives access to them.

See Section 5.2.1, Section 5.2.3 and Section 5.2.4.

8.1.2. Exchanging events between API implementations

The consistency requirement for the "Customer Self-Service App" product leads to the
conclusion that the command-query paths shown in Figure 90 must be "short-circuited" such
that also very recent claim submissions, which are not yet exposed by the Motor Claims
System, can be retrieved via the "Claims Process API" and "Motor Claims Search System API".

One way of architecting this "short-circuit" is through an approach not unlike CQRS and event
sourcing:

1. The "Motor Claims Submission System API", after transmitting a claim submission to the
Motor Claims System, must also publish a "Motor Claim Submitted" event.

© 2017 MuleSoft Inc. 143

Anypoint Platform Architecture Application Network Design

2. The "Motor Claims Search System API", in addition to retrieving claims from the Motor
Claims System, must also consume "Motor Claim Submitted" events, store them and
include them in the search results it returns to its API clients, specifically the "Claims
Process API".

This amounts to a non-API communication channel between the "Motor Claims Submission
System API" and the "Motor Claims Search System API" that follows the general architectural
principles of Event-Driven Architecture.

Claims Query Claim Submission

Command

Process APIs

Claims API Motor Claims

Submission API

System APIs

Motor Claims Motor Claim Motor Claims

Search API Submitted Submission API

Motor Claims
System

Figure 91. To make recent claim submissions, which are not yet exposed by the Motor Claims
System, available to the "Motor Claims Search System API", the latter consumes "Motor Claim
Submitted" events published by the "Motor Claims Submission System API"

8.1.3. Exercise 13: Event exchange patterns and

responsibilities in API-led connectivity
The previous discussion assumed that "Motor Claim Submitted" events are published by a
System API and consumed by another System API. The same consistency requirement could
also have been realized by other APIs acting as event producers and consumers:

• Events are published by "Motor Claims Submission System API" and consumed by "Motor
Claims Search System API" (see Figure 91)
• Events are published by "Motor Claims Submission System API" and consumed by "Claims
Process API"
• Events are published by "Motor Claims Submission Process API" and consumed by "Motor
Claims Search System API"
• Events are published by "Motor Claims Submission Process API" and consumed by "Claims

© 2017 MuleSoft Inc. 144

Anypoint Platform Architecture Application Network Design

Process API"
1. Discuss the characteristics of each of these four event exchange patterns.
2. Are there general rules akin to the API invocation rules of API-led connectivity that can
be extracted from this example?

Solution

See Section 8.1.4.

8.1.4. Separating concerns when exchanging events between

API implementations
What are architectural considerations that should be taken into account when exchanging
events between API implementations, for instance as depicted in Figure 91?:

• If "Motor Claim Submitted" captures the historical fact that a claim submission has been
(successfully) passed to the Motor Claims System then the publishing of that event should
occur as close to the Motor Claims System as possible, i.e., in the "Motor Claims Search
System API".
• If the API implementation of a System API publishes an event then it should only be
consumed by the API implementation of a System API or Process API: see Section 8.2.5.
• The publishing and consumption of events in a System API adds responsibilities to that
System API that are unrelated to backend system connectivity (thereby violating the Single
Responsibility Principle). This "muddling" of responsibilities is trivial in the case of event
publishing but significant in the case of event consumption and storage. It should therefore
be avoided that System APIs also consume and store events in addition to performing
"normal" backend connectivity.
• An architecturally clean solution therefore mandates a new System API that consumes and
stores "Motor Claim Submitted" events - the "Submitted Motor Claims Search System API" -
and requires the existing "Claims Process API" to coordinate between the two types of
System APIs that search against motor claims ("Motor Claims Search System API" and
"Submitted Motor Claims Search System API"). This is captured in Figure 92, which hence
improves on and replaces Figure 91.
◦ This is another example of the claim made in Section 2.2.13 that application networks
"bend but do not break": the consistency requirement for the "Customer Self-Service
App" product was added to an existing application network by changig a System API
("Motor Claims Submission System API"), adding a System API ("Submitted Motor
Claims Search System API") and changing the API implementation but not the API
specification of a Process API ("Claims Process API").

© 2017 MuleSoft Inc. 145

Anypoint Platform Architecture Application Network Design

Claims Query Claim Submission

Command

Process APIs

Claims API Motor Claims

Submission API

System APIs

Motor Claims Submitted Motor Claim Motor Claims

Search API Motor Claims Submitted Submission API
Search API

Motor Claims
System

Figure 92. Architecturally clean separation of concerns between "Motor Claims Search System
API" for accessing the Motor Claims System and the new "Submitted Motor Claims Search
System API" for consuming "Motor Claim Submitted" events published by the "Motor Claims
Submission System API". The event store used by "Submitted Motor Claims Search System
API" to persist and search "Motor Claim Submitted" events is not shown

8.2. Understanding the value of Event-Driven

Architecture in the context of API-led connectivity

8.2.1. Defining Event-Driven Architecture

See the corresponding glossary entry.

8.2.2. Exercise 14: Differences between API-led connectivity

and Event-Driven Architecture
Drawing on your experience and the preceding discussions:

1. List differences and similarities between events and APIs

2. List differences and similarities between Event-Driven Architecture and API-led connectivity
3. Does Event-Driven Architecture lead to the emergence of an application network?
4. If so, what are the consumable assets associated with Event-Driven Architecture?

© 2017 MuleSoft Inc. 146

Anypoint Platform Architecture Application Network Design

Solution

See Section 8.2.3 and Section 8.2.4.

8.2.3. Comparing events and APIs

Events as used in Event-Driven Architecture and APIs as used in API-led connectivity can be
compared and contrasted along the following dimensions:

• Programmatic: Both are primarily programmatic communication approaches in nature, i.e.,

intended for communication between application components.
• Meaning: An event is (or captures/describes) a state change that has occurred in the
application component that acts as the event producer, whereas an API is a programmatic
interface to a service provided by the application component exposing that API (the target
of the API invocation).
• Dynamic nature: An event is therefore more similar to an API invocation than to an API,
i.e., it is a concrete instance of the communication between application components. Even
then, the API invocation, for instance for a REST API, is a combination of resource and HTTP
method and therefore typically denotes an action to be performed upon execution of the
API invocation, whereas an event describes what has already happened.
• Static nature: Events denoting state changes of the same kind are said to be of the same
event type. This is the equivalent of the API and specifically the data model used in the API
specification.
• Granularity: An event/event type is typically for one well-defined state change, whereas an
API can expose many resources and support many HTTP methods per resource. Thus an
API is more akin to a group of event types than a single event type.
• Synchronicity: API invocations are by definition synchronous, consisting of request and
synchronous response (even though the processing triggered by an API invocation can be
performed asynchronously, as discussed for instance in Section 6.4.1). Thus if API client
and API implementation are not both available throughout the duration of the API
invocation then that API invocation fails. Events by contrast are exchanged asynchronously
(as messages) and therefore event producer and consumer are decoupled in time.
• Communication path: An API invocation is from one API client to one API implementation,
and the API client specifically addresses the API implementation. (API proxies are a stand-
in for the API implementation, must be explicitly targeted by the API client, and therefore
do not change the nature of this argument.) Events are sent by an event producer to a
destination (queue, topic, message exchange; depending on messaging paradigm) and are
then received by event consumers from that destination - without the producer being aware
of the consumers or the consumers being aware of the producer. Furthermore, there can be
more than one consumer for each event.

© 2017 MuleSoft Inc. 147

Anypoint Platform Architecture Application Network Design

• Broker: Exchanging events requires a message broker, such as Anypoint MQ, as the owner
of destinations, whereas API invocations, at a minimum, only require API client and API
implementation.
• Contract: The contract for an API is its API specification, typically a RAML definition. The
contract for an event is the combination of destination and event (data) type and is not
typically captured formally.

8.2.4. Comparing Event-Driven Architecture and API-led

connectivity
API-led connectivity defines the three tiers of Experience APIs, Process APIs and System APIs.
Although application components exchanging events can be organized similarly, this is not an
inherent part of Event-Driven Architecture.

API-led connectivity restricts communication patterns according to these three tiers

(essentially top to bottom), whereas application components exchanging events do not a-priori
have to adhere to the same communication pattern restrictions.

API implementations typically have well-defined static dependencies on other APIs and/or
backend systems (see Figure 38 for an example). While similar relationships may materialize
in Event-Driven Architecture at runtime, there are no static dependencies between the
application components exchanging events. Instead, these application components only
depend on the exchanged event types, the destinations and the message broker hosting those
destinations. Furthermore, event consumers may change dynamically at any time, thereby
dynamically reconfiguring the relationship graph of the application components in an Event-
Driven Architecture, without the event producers becoming aware of that change.

Event-Driven Architecture requires a message broker as an additional component of the

Technology Architecture, with all application components who want to exchange events having
to agree on the same message broker (this is not a strict requirement in some broker
architectures).

API-led connectivity and in particular application networks are defined by the API-centric
assets published for self-service consumption. The equivalent for Event-Driven Architecture
would revolve around destination and event types.

Enforcing NFRs by applying API policies in Anypoint API Manager on top of existing API
implementations has no equivalent in Event-Driven Architecture on Anypoint Platform.

8.2.5. Event exchange patterns in API-led connectivity

API-led connectivity imposes the architectural constraint that Experience APIs must only

© 2017 MuleSoft Inc. 148

Anypoint Platform Architecture Application Network Design

invoke Process APIs, Process APIs must only invoke System APIs or other Process APIs, and
System APIs must only communicate with backend systems. This constraint brings order and
predictability to the communication patterns in an application network.

When Event-Driven Architecture is applied in the context of API-led connectivity then the
application components exchanging events are predominantly API implementations.

Event-Driven Architecture by itself is agnostic about the three tiers of API-led connectivity and
hence does not restrict event exchanges between API implementations in different tiers. But
breaking the communication patterns of API-led connectivity through arbitrary, unrestricted
event exchanges risks destroying the order and structure created in an application network by
the application of API-led connectivity.

Importantly, API-led connectivity is an API-first approach, which does not rule-out the
exchange of events, but views it as an exceptional addition to API invocations as the dominant
form of communication between application components. It is therefore advisable to require
API implementations that exchange events to follow communication patterns in accordance
with API-led connectivity:

• Any API implementation that publishes events should define its own destinations (queues,
message exchanges) to send these events to. Often, there will be one destination per event
type published by that API implementation.
• In this way destinations belong logically to the same API-led connectivity tier as the API
implementation publishing events to them.
◦ I.e., a System API publishes events to destinations that logically belong to the System
API tier and can hence be described as "system events"
◦ I.e., a Process API publishes events to destinations that logically belong to the Process
API tier and can hence be described as "process events"
◦ I.e., an Experience API publishes events to destinations that logically belong to the
Experience API tier and can hence be described as "experience events"
• Any API implementation that consumes events must not do so from a destination that
belongs to a higher tier than the consuming API implementation itself. In other words,
events must not flow downwards across the tiers of API-led connectivity:
◦ Events published by Experience APIs to their destinations ("experience events") must
not be consumed from those destinations by Process APIs or System APIs.
◦ Events published by Process APIs to their destinations ("process events") must not be
consumed from those destinations by System APIs.
◦ Put differently: Events may only be consumed within the same tier or in higher tiers
relative to the API implementation that publishes the events.

© 2017 MuleSoft Inc. 149

Anypoint Platform Architecture Application Network Design

◦ The logic for this rule is the same as for the communication patterns underlying API-led
connectivity: the rate of change of Experience APIs (which are relatively volatile) is
higher than the rate of change of Process APIs which is higher than the rate of change of
System APIs (which are comparatively stable). And a slow-changing component must
never depend on a fast-changing component.
• In addition, in analogy with API-led connectivity, it should be prohibited that Experience
APIs directly consume events published by System APIs, thereby bypassing Process APIs.

Experience Experience
APIs Events

API invocations

Process APIs Process

Events

API invocations

System APIs System

Events

Figure 93. Flow of events and API invocations in API-led connectivity augmented with
elements from Event-Driven Architecture, with API invocations between Process APIs omitted

8.3. Adding support for asynchronous messaging to the

Technology Architecture

8.3.1. Introducing Anypoint MQ

Anypoint MQ

• is Anypoint Platform’s multi-tenant cloud-based (hosted) messaging service

• that is only available in the MuleSoft-hosted Anypoint Platform
• offers role-based access-control in line with the rest of Anypoint Platform
• provides token-based client access control
• implements an async messaging model using queues, message exchanges and bindings
between them

© 2017 MuleSoft Inc. 150

Anypoint Platform Architecture Application Network Design

• supports: point-to-point, pub/sub, FIFO queues, payload encryption, persistent/durable

messages, DLQs, message TTL
• exposes a REST API and an Anypoint Connector for the Mule runtime on top of that
◦ This means that message producers and consumers can be located anywhere, as long as
they can make API invocations to the MuleSoft-hosted Anypoint MQ broker.
• has a web-based management console in the Anypoint Platform web UI

In Anypoint MQ, messages can be sent to queues or message exchanges and consumed only
from queues. Message exchanges must therefore be (statically) configured to distribute the
messages sent to them to one or more queues in order for those messages to be consumable.

8.3.2. Event-Driven Architecture with Anypoint MQ for the

"Customer Self-Service App" product
See also Figure 92.

© 2017 MuleSoft Inc. 151

Anypoint Platform Architecture Application Network Design

Motor Claims Motor Claims Submitted Motor

Submission API System Motor Claim Submitted Motor Claim Submitted Claims Search API
Message Exchange Message Queue Event Store

Publish event
HTTP PUT
body: claim submission

claim submission

Motor Claim Submitted event

HTTP response

Distribute event
event

Consume event
Motor Claim Submitted event

store event

Search events
HTTP GET
query params: search criteria

search

matching events

HTTP response
body: search results

Motor Claims Motor Claims Motor Claim Submitted Motor Claim Submitted Submitted Motor Event Store
Message Exchange Message Queue
Submission API System Claims Search API

Figure 94. "Motor Claims Submission System API" produces "Motor Claim Submitted" events
by publishing them to an Anypoint MQ message exchange, from where they are consumed by
"Submitted Motor Claims Search System API" and stored in an event store (an external
database or potentially a Mule runtime Object Store), such that when a search request arrives
at "Submitted Motor Claims Search System API" it can respond by searching that event store
for matching "Motor Claim Submitted" events

Summary
• Some NFRs are best realized by following Event-Driven Architecture paradigms in addition
to API-led connectivity
• Events describe historical facts and are exchanged asynchronously between application
components via destinations such as message exchanges
• Event exchange patterns should follow the rules established by API-led connectivity
• Anypoint MQ is a MuleSoft-hosted multi-tenant cloud-native messaging service that can be
used to implement Event-Driven Architecture
• The consistency requirement of the "Customer Self-Service App" product can be realized by
introducing a new System API that consumes events published by the "Motor Claims
Submission System API"

© 2017 MuleSoft Inc. 152

Anypoint Platform Architecture Application Network Design

Chapter 9. Transitioning Into Production

Objectives
• Locate API-related activities on a development lifecycle
• Interpret DevOps using Anypoint Platform tools and features
• Design automated tests from the viewpoint of API-led connectivity and the application
network
• Understand the factors involved in scaling API performance
• Know how to deprecate and delete an API version in Anypoint Platform
• Reflect on single points of failure

9.1. Understanding the development lifecycle and

DevOps

9.1.1. Keeping the development lifecycle in perspective

MuleSoft’s proposed lifecycle for developing API-led connectivity integration solutions, depicted
in Figure 95, is API-first and therefore

• starts with API-centric activities that lead to the creation of an API specification
• then proceeds to building the API implementation
• before transitioning both the API as well as the API implementation into production

Each of these three phases is supported by Anypoint Platform components, as shown in Figure
95.

© 2017 MuleSoft Inc. 153

Anypoint Platform Architecture Application Network Design

Figure 95. The API-centric development lifecycle and Anypoint Platform components
supporting it

9.1.2. Building on a strong DevOps foundation

For the health of the application network it is paramount that the process by which API
implementations are created and deployed to production is reliable, reproducible and as much
as possible automated. This is because defects or failures in business-critical API
implementations have the potential of affecting the application network. Therefore, strong
DevOps capabilities and a rigorous development and deployment process are an absolute
necessity.

Acme Insurance, with strong guidance from the C4E, standardizes on the following DevOps
principles:

• All RAML definitions and RAML fragments must live in an artifact repository
◦ Acme Insurance chooses Anypoint Exchange which is a Maven-compatible artifact
repository
• All source code for API implementations must live in a source code repository
◦ Acme Insurance chooses Git and GitHub, with every API implementation having its own
GitHub repo

The chosen development and DevOps process is roughly as follows:

1. Developers of an API implementation implement on short-lived feature branches off the Git
develop branch of that API implementation’s repo
a. This is the GitFlow branching model

© 2017 MuleSoft Inc. 154

Anypoint Platform Architecture Application Network Design

2. Developers implement the Mule application and all types of automated tests (unit,
integration, end-to-end, performance) and make them pass
a. Acme Insurance chooses a combination of Anypoint Studio, JUnit, MUnit, SOAPUI and
JMeter
b. For build automation Acme Insurance chooses Maven and suitable plugins such as the
Mule Maven plugin, the MUnit Maven plugin and those for SOAPUI and JMeter
3. Once done, developers submit GitHub pull requests from their feature branch into the
develop branch
4. A developer from the same team performs a complete code review of the pull request,
confirms that all tests pass, and, if satisfied, merges the pull request into the develop
branch of the API implementation’s GitHub repo
5. This triggers the CI pipeline:
a. Acme Insurance chooses Jenkins, delegating to Maven builds to implement CI/CD
b. The API implementation Mule application is compiled, packaged and all unit and
integration tests are run
c. The Mule application is deployed to an artifact repository
i. Acme Insurance chooses a private Nexus installation
6. When sufficient features have accumulated for the API implementation, the release
manager for that API implementation "cuts a release" by tagging, creating a release branch
and ultimately merging into the master branch of the API implementation’s repo
7. This triggers the CI/CD pipeline in Jenkins:
a. The CI pipeline is executed, leading to deployment of the API implementation into an
artifact repository
b. Automatically, and/or through a manual trigger, the CD pipeline is executed:
i. A well-defined version of the Mule application from the artifact repository is deployed
into a staging environment
ii. End-to-end tests and performance tests are run over HTTP/S against the API exposed
by the API implementation
iii. Upon success the Mule application from the artifact repository is deployed into the
production environment
iv. The "deployment verification sub-set" of the functional end-to-end tests is run to
verify the success of the deployment
A. Failure leads to immediate rollback via the execution of the CD pipeline with the
last good version of the API implementation

Anypoint Platform has no direct support for "canary deployments", i.e. the practice of initially
only directing a small portion of production traffic to the newly deployed API implementation.

© 2017 MuleSoft Inc. 155

Anypoint Platform Architecture Application Network Design

The above discussion assumes that a previous version of the API implementation in question
has already been developed, and that, therefore, the Anypoint API Manager and API policy
configuration for the API exposed by the API implementation is already in place. Creation of
this configuration can be automated with the Anypoint Platform APIs.

Figure 96. The GitFlow branching model showing the master and develop branch as well as
release and feature branches. Source: Atlassian

9.2. Designing automated tests for APIs, API

implementations and the application network

9.2.1. Introducing API-centric automated testing

The practice of testing does not change fundamentally when API-led connectivity is employed
and application networks are grown. All the same types of tests and activities of preparing for,
executing and reporting on tests are still applicable. Therefore this discussion addresses only a
few selected topics that are of special interest in the context of API-led connectivity and
application networks.

Due to the interconnected nature of the application network, resilience tests become
particularly important in establishing confidence in the fail-safety of the application network -
see Section 9.2.4.

Unsurprisingly, APIs and API specifications take center stage when testing application
networks.

A distinction can be made between integration tests and end-to-end tests:

• Integration tests
◦ Do not require deployment into any special environment, such as a staging environment

© 2017 MuleSoft Inc. 156

Anypoint Platform Architecture Application Network Design

◦ Can be run from within an embedded Mule runtime

◦ Can/should be implemented using MUnit
▪ For read-only interactions to any dependencies (such as other APIs): allowed to
invoke production endpoints
▪ For write interactions: developers must implement mocks using MUnit
• End-to-end tests
◦ Exercise the API just like production API invocations would, i.e., over HTTP/S with API
policies applied
◦ Require deployment into a staging environment with all dependencies available just as in
production
▪ No mocking is permissible
◦ Can be implemented using SOAPUI and its Maven plugin to trigger API invocations
against the deployed API implementation and assert responses

9.2.2. Designing automated API-centric end-to-end tests

• You define test scenarios for each of the APIs in Acme Insurance’s application network
• The scenarios should comprise both functional and non-functional tests, including
performance tests
• The test scenarios for an API are driven by the API specification and, in particular, the RAML
definition of the API
◦ Test scenarios and test cases should be defined on the basis of just the discoverable
documentation available from the API Portal and Anypoint Exchange entry of the API
(black-box tests)
▪ This guards against pointlessly driving tests for an API by the actual API
implementation
▪ It also highlights deficiencies of the API’s discoverable documentation
◦ There should not be a single interaction in the API Notebook of an API that is not
covered by a test scenario
• You automatically execute the test cases for each API by invoking an actual API endpoint
over HTTP/S
• The most basic (and per-se insufficient) test assertions are those that test for adherence to
the RAML definition in terms of data types, media types, etc.
• Must execute in special production-like staging environment
◦ Alert dependencies before performance tests are run!
• A safe sub-set of end-to-end tests can also be run in production as a "deployment

© 2017 MuleSoft Inc. 157

Anypoint Platform Architecture Application Network Design

verification test suite"

9.2.3. Unit testing API implementations

API implementations are typically characterized by numerous and complex interactions with
other systems:

• Experience APIs such as the "Aggregator Quote Creation Experience API" invoke Process
APIs such as the "Policy Holder Search Process API"
• Process APIs such as the "Policy Holder Summary Process API" invoke other Process APIs
such as the "Policy Holder Search Process API" and/or System APIs such as the "Motor
Policy Holder Search System API"
• System APIs such as the "Motor Policy Holder Search System API" interact with backend
systems such as the Policy Admin System over whatever protocol the backend system
supports (MQ in the case of the Policy Admin System)

Unit testing such complex API implementations can be daunting due to the need for dealing
with all these dependencies of an API implementation.

With MUnit Anypoint Platform provides a dedicated unit testing tool that

• is specifically designed for unit testing Mule applications

• can stub-out external dependencies of a Mule application
• has dedicated IDE-support in Anypoint Studio
• can be invoked from Maven builds using the MUnit Maven plugin

9.2.4. Testing the resilience of application networks

The foundation of application networks is a web of highly interconnected APIs. Resilience
testing is the practice of disrupting that web and asserting that the resulting inevitable
degradation of the quality of all relevant services offered by/on the application network is
within acceptable limits.

Resilience testing is an important practice in the move to API-led connectivity and application
networks.

Acme Insurance plans to implement resilience testing using the following automated approach:

• Using a software tool similar in spirit to Chaos Monkey

• which acts as an API client to the API Platform API
• and with the help of this API automatically adds, configures and removes API policies on all

© 2017 MuleSoft Inc. 158

Anypoint Platform Architecture Application Network Design

APIs in (a test sub-set of) the application network

• where the API policies manipulated by the tool aim to erratically throttle or interrupt
invocations of the APIs to which they are applied

While this resilience testing tool runs and disrupts the application network, "normal"
automated end-to-end tests are executed.

Also see [Ref11].

9.2.5. Exercise 15: Reflect on resilience testing

Think back on your experience with resilience testing complex distributed systems in any
organization you have worked with:

1. In your experience, is resilience testing an established part of organizations' testing

strategy?
2. Should resilience tests be run against the production environment?
a. What about performance tests?
3. Does focusing resilience testing on API invocations make this an easier practice?
4. Does it reduce the effectiveness of resilience testing compared to more general resilience
testing approaches?

Solution

9.2.6. End-to-end test scenarios for Acme Insurance

A small selection of end-to-end test scenarios and classes of test cases for Acme Insurance:

• "Aggregator Quote Creation Experience API":

◦ Invoke with valid, invalid and missing policy description from Aggregator
◦ Invoke for existing and new policy holder
◦ Invoke for policy holder with a perfectly matching in-force policy
◦ Invoke at 500, 1000 and 1500 requs/s
◦ Invoke over HTTP and HTTPS
◦ Invoke from API client with valid, expired and invalid client-side certificate
• "Motor Policy Holder Search System API":
◦ Invoke with valid, invalid and missing search criteria
◦ Invoke for search criteria matching 0, 1, 2 and almost-all policy holders

© 2017 MuleSoft Inc. 159

Anypoint Platform Architecture Application Network Design

◦ Invoke for policy holder with only home and no motor policies
◦ Invoke at 500, 1000 and 1500 requs/s
◦ Invoke with valid and invalid client token and without client taken
• "Motor Claims Submission Process API":
◦ …
◦ Invoke polling endpoint once per original request, 1000 times per second, not at all

Test cases based on the above test scenarios should be executed

• with the application network in a (supposedly) healthy state

• while Chaos Monkey-like resilience tests are disrupting the application network

9.3. Scaling the application network

9.3.1. Ways to scale the performance of an API

Given an API and its API implementation, there are two main ways of scaling (typically:
increasing) the performance of that API:

• Vertical scaling, i.e., scaling the performance of each node on which a Mule runtime and a
deployed API implementation or API proxy executes
◦ In CloudHub this is supported through different worker sizes (see Section 7.1.4)
• Horizontal scaling, i.e., scaling the number of nodes on which Mule runtimes and deployed
API implementations or API proxies executes
◦ In CloudHub and Anypoint Platform for Pivotal Cloud Foundry this is supported through
scaleout and load balancing, currently with a limit of 8 workers per API implementation

If separate API proxies are deployed in addition to API implementations then the two types of
nodes can be scaled independently. In most real-world cases the performance-limiting node is
the API implementation and not the API proxy, hence there typically need to be more/larger
instances of the API implementation than the corresponding API proxy.

9.3.2. An API scales for its API clients

Because an API’s raison d’être is to be consumed by API clients, the QoS and performance
characteristics of an API must suit these API clients. The same is true for the change in these
performance characteristics over time - the scaling of the API performance over time.

It is therefore essential that the team responsible for an API understands the projected
performance needs of all its API’s API clients and is prepared to scale their API’s performance

© 2017 MuleSoft Inc. 160

Anypoint Platform Architecture Application Network Design

to meet those needs.

9.3.3. The C4E owns systemic performance considerations

APIs do not exist alone. They do not even exist just for their API clients. A the end of the day,
all APIs exist to meet strategic business goals and requirements, such as

• to create new sales channels by opening to Aggregators,

• or to reduce cost by providing customer self-service capabilities.

See Figure 3.

The performance of any individual API in the Acme Insurance application network is only
important insofar as it enables and supports these strategic business objectives.

It is therefore not efficient if individual APIs provide performance that is unbalanced with
respect to the performance of other APIs in the application network. For instance, stellar
response time of the "Mobile Auto Claim Submission Experience API" used in the "Submit auto
claim" feature is irrelevant if the "Retrieve policy holder summary" feature is so slow that the
user is put off from ever executing the "Submit auto claim" feature.

What this means is that there is a systemic perspective on API performance, i.e., a viewpoint
that calls for an application network-wide analysis of API performance. This systemic viewpoint
must consider

• dependencies between APIs

• the business objectives to which each API ultimately contributes
• and the relative importance of these business objectives, now and in the future.

Application network-wide performance analysis and governance is a responsibility best

assigned to the C4E. The data for this type of analysis can be extracted from Anypoint
Platform through the Anypoint Platform APIs.

9.4. Gracefully ending the life of an API

9.4.1. End-of-live management on the level of API version

instead of API implementation
The needs of an API client are fulfilled

• if it can successfully send API invocations to the published endpoint of an API

© 2017 MuleSoft Inc. 161

Anypoint Platform Architecture Application Network Design

• and if it receives responses in accordance with the contract and expected QoS of the API.

This process requires an API implementation of that API to be available and to live up to the
expected QoS standards. But since the API client is not aware of the API implementation itself
- it is only aware of the API it exposes at a certain endpoint - the API implementation can be
changed, updated and replaced without alerting the API client.

On the other hand, any change to the API, its contract or promised QoS, that is not entirely
backwards-compatible needs to be communicated to all API clients of that API. This is done
through the introduction of a new version of the API - and the subsequent phased ending of
the live of the previous API version.

9.4.2. Deprecating and deleting an API version on Anypoint

Platform
Anypoint Platform supports end-of-live management of APIs as follows:

• In Anypoint API Manager an API version can be set to deprecated

◦ This prevents new API clients from requesting access to that API version
• At a later stage, the API version can then be deleted

Figure 97. Option to deprecate or delete a version of the "Aggregator Quote Creation
Experience API" in Anypoint API Manager

© 2017 MuleSoft Inc. 162

Anypoint Platform Architecture Application Network Design

Figure 98. Deprecated versions of "Aggregator Quote Creation Experience API" in Anypoint API
Manager

Figure 99. Deprecated versions of "Aggregator Quote Creation Experience API" in Acme
Insurance's Developer Portal

Figure 100. The API Portal of a deprecated version of "Aggregator Quote Creation Experience
API" does not allow the API consumer to request API access

© 2017 MuleSoft Inc. 163

Anypoint Platform Architecture Application Network Design

9.5. Identifying points of failure

9.5.1. Exercise 16: Identify points of failure in Acme

Insurance's application network
Assume a deployment of all APIs in Acme Insurance’s application network to a MuleSoft-hosted
Anypoint Platform using CloudHub:

1. Identify all points of failure in this architecture.

2. Are there any components that are not redundant, i.e., that constitute single points of
failure?

See Figure 56.

Solution

• Potential points of failure are everywhere: every node and system involved in processing
API invocations is a potential point of failure.
• For instance, failure of the Anypoint API Manager would mean that
◦ Already-applied API policies continue being in force
◦ New Mule runtimes that start-up (and are configured with the gatekeeper feature) will
not become functional until they can download API policies from the Anypoint API
Manager
◦ Continued unavailability of the Anypoint API Manager would lead to overflow of the
buffers in the Mule runtime that hold undelivered API analytics events
• Single points of failure are much rarer
◦ At first sight it seems as if there were no single points of failure
◦ Every API implementation that is deployed to only one CloudHub worker constitutes a
single point of failure (although CloudHub is typically configured to auto-restart failed
workers and hence the duration of failure is relatively short)
◦ There is little information about the Home Claims System and it may therefore
potentially contain single points of failures.
◦ Every deployment of an API implementation, in its entirety, constitutes a single point of
failure: If the deployment of an API implementation technically succeeds but deploys a
deficient API implementation, then API invocations to that API will fail. Thus this API now
constitutes an actually failed single point of failure for all API clients of that API (but they
may have a fallback API to invoke). This highlights the importance of reliable and fully
automated DevOps and testing processes, including a "deployment verification test
suite".

© 2017 MuleSoft Inc. 164

Anypoint Platform Architecture Application Network Design

Summary
• API definition, implementation and management can be organized along an API
development lifecycle
• DevOps on Anypoint Platform builds on and supports well-known tools like Jenkins and
Maven
• API-centric automated testing augments standard testing approaches with an emphasis on
end-to-end tests and resilience tests
• Scaling API performance must match the API clients' needs and requires the C4E’s
application network-wide perspective
• Anypoint Platform supports gracefully decommissioning API versions using deprecation
• Anypoint Platform has no inherent single points of failure but every deployment of an API
implementation can become one

© 2017 MuleSoft Inc. 165

Anypoint Platform Architecture Application Network Design

Chapter 10. Monitoring and Analyzing the

Behavior of the Application Network

Objectives
• Understand the origin of data used in monitoring, analysis and alerting on Anypoint
Platform
• Know the metrics collected by Anypoint Platform on the level of API invocations
• Know the grouping of API metrics available in Anypoint Analytics
• Know available options for performing API analytics within and outside of Anypoint Platform
• Define alerts for key metrics of API invocations for all tiers of API-led connectivity
• Understand how metrics and alerts for API implementations augment those for API
invocations
• Recognize operations teams as an important stakeholder in API-related assets and organize
documentation accordingly

10.1. Understanding monitoring data flow in Anypoint

Platform

10.1.1. Data flows for Anypoint Platform monitoring, analytics

and alerting
Compare also with Table 1.

© 2017 MuleSoft Inc. 166

Anypoint Platform Architecture Application Network Design

Anypoint Platform

API Manager Analytics Runtime

Web UI Web UI Manager
Web UI

API Platform Analytics Monitoring Runtime Analytics Runtime Mgr CloudHub Cloudhub
API Events API Query API Manager API Ingest API Private API Enhanced
Interface Logging API

Mule event metrics, JMX metrics

incl. API policy

API analytics events API analytics events Mule events JMX metrics
violations

External External External

Reporting Analytics Monitoring
(Splunk, ...) (Nagios, ...)

Mule runtime node

Mule runtime API

implementation
or proxy

Figure 101. Different types of data used for monitoring, analytics and alerting flow from Mule
runtimes to Anypoint Platform components like Anypoint Runtime Manager, Anypoint API
Manager and Anypoint Analytics and/or to external systems. Not all options are available in all
Anypoint Platform deployment scenarios

10.2. Using Anypoint Analytics to gain insight into API

invocations

10.2.1. Metrics in Anypoint Analytics

Anypoint Analytics provides features for analyzing API invocations based on various metrics,
such as:

• Number of API invocations (requests)

◦ Successful, i.e., those with a HTTP response status code in range [100, 400)
◦ Unsuccessful due to a client error, i.e., those with a HTTP response status code in range
[400, 500)
◦ Unsuccessful due to a server error, i.e., those with a HTTP response status code in range
[500, 600)
• Mean response time (average latency)
• Request and response payload size
• Properties of the API client such as its client ID (if registered), geographical location, OS
platform, etc.

© 2017 MuleSoft Inc. 167

Anypoint Platform Architecture Application Network Design

• Properties of the API invocation itself such as resource path, HTTP method, etc.

Note that only for REST APIs are HTTP response status codes indicative of success, failure and
reason for that failure.

Metrics can be grouped and displayed along various dimensions:

• per API for all API clients

• per API and API client
• per API client for all APIs
• custom

Figure 102. Number of API invocations (requests) over time for a given API and all its API
clients, grouped by HTTP status code class

© 2017 MuleSoft Inc. 168

Anypoint Platform Architecture Application Network Design

Figure 103. Mean response time (average latency) of API invocations over time for a given API
and all its API clients and all HTTP status codes

10.2.2. Analyzing API invocations to the "Mobile Auto Claim

Submission Experience API"

Figure 104. Number of API invocations (requests) over time to the "Mobile Auto Claim
Submission Experience API", grouped by each of its top 5 API clients

10.2.3. Analyzing API invocations to the "Policy Holder Search

Process API"

© 2017 MuleSoft Inc. 169

Anypoint Platform Architecture Application Network Design

Figure 105. Number of API invocations (requests) over time to the "Policy Holder Search
Process API", grouped by each of its top 5 API clients

10.2.4. Analyzing API invocations from the perspective of the

Customer Self-Service Mobile App
An API consumer is typically interested in analytics of all API invocations performed by their
API clients. An example of this is the Customer Self-Service Mobile App.

Figure 106. Overview of API invocations from the Customer Self-Service Mobile App to all APIs
it invokes - which are, by definition, Experience APIs

© 2017 MuleSoft Inc. 170

Anypoint Platform Architecture Application Network Design

10.3. Analyzing API invocations across the application

network

10.3.1. Introducing application network-wide API analytics

The Anypoint Analytics component of Anypoint Platform can be used to perform standard and
custom analyses across all API invocations in an application network:

• Interactive exploration through drill-down

• Definition of custom charts and dashboards
• Definition of custom reports
• Exporting all data underlying a graph to CSV files
• Programmatic access to all data via Anypoint Platform APIs

10.3.2. API invocation analysis by geography

Figure 107. Number of API invocations from all API clients to all Experience APIs, grouped by
geography

10.3.3. API invocation analysis by API client

© 2017 MuleSoft Inc. 171

Anypoint Platform Architecture Application Network Design

Figure 108. Number of API invocations to all Experience APIs, grouped by API clients

10.3.4. API invocation analysis by response time

Figure 109. Custom chart showing average (mean) response time per API invocation in
milliseconds for the top 5 slowest APIs, for the last 90 days

10.3.5. API governance analysis

© 2017 MuleSoft Inc. 172

Anypoint Platform Architecture Application Network Design

Figure 110. Custom chart showing number of policy violations, grouped by API policy and API
client

10.4. Defining alerts for exceptional occurrences in an

application network

10.4.1. Introducing alerts at the level of API invocations

Anypoint Platform can raise alerts based on these metrics of API invocations:

• Number of violations of a given policy

• Request count (number of API invocations)
• Response code in given list of HTTP response status codes
• Response time exceeding given threshold in milliseconds

For each of these metrics Anypoint Platform typically triggers an alert when the metric

• falls above (or below) a given threshold

• for a given number of time periods of a given length

© 2017 MuleSoft Inc. 173

Anypoint Platform Architecture Application Network Design

Figure 111. Some of the alerts based on API invocations in the Acme Insurance application
network

10.4.2. Defining alerts for "Aggregator Quote Creation

Experience API"
Following C4E guidelines, you define alerts for Experience APIs as follows:

• for all violations of API policies,

• for all violations of QoS guarantees not captured in API policies

Applying this to "Aggregator Quote Creation Experience API", referring to the NFRs and API
policies for this API.

• "SLA tier exhausted for "Aggregator Quote Creation Experience API"": for violation of SLA-
based Rate Limiting, severity Info, more than 60 violations for at least 3 consecutive 10-
minute periods
◦ Alerts when approx. 10% of 1-second intervals are above SLA tier-defined rate limit
• "TLS mutual auth circumvented for "Aggregator Quote Creation Experience API"": for
violation of IP whitelist, severity Critical, more than 1 violation for at least 3 consecutive 1-
minute periods
• "XML attack on "Aggregator Quote Creation Experience API"": for violation of XML threat
protection, severity Warning, more than 30000 violations for at least 3 consecutive 10-

© 2017 MuleSoft Inc. 174

Anypoint Platform Architecture Application Network Design

minute periods
◦ Alerts when approx. 5% of requests (5% of 1000*60*10 = 30000) are identified as XML
threats
• "Response time QoS guarantee violated by "Aggregator Quote Creation Experience API"":
severity Warning, more than 6000 requests whose response time exceeds 400 ms, for at
least 3 consecutive 10-minute periods
◦ Alerts when approx. 1% of API invocations (1% of 1000*60*10 = 6000) take longer
than 400 ms
◦ Note that exact QoS guarantee cannot be expressed in alert: median = 200 ms,
maximum = 500 ms

Figure 112. Alerts defined for the "Aggregator Quote Creation Experience API"

10.4.3. Defining alerts for "Policy Options Retrieval System

API"
Following C4E guidelines, you define alerts for System APIs as follows:

• for all violations of API policies

Applying this to "Policy Options Retrieval System API", referring to the NFRs and API policies
applicable to this API.

• "SLA tier exhausted for "Policy Options Retrieval System API"": for violation of SLA-based
Throttling, severity Info, more than 60 violations for at least 3 consecutive 10-minute
periods
◦ Alerts when approx. 10% of 1-second intervals are above SLA tier-defined rate limit
◦ Also alerts on invalid client ID/secret supplied

© 2017 MuleSoft Inc. 175

Anypoint Platform Architecture Application Network Design

• "Client not in Process API subnet for "Policy Options Retrieval System API"": for violation of
IP whitelist, severity Critical, more than 1 violation for at least 3 consecutive 1-minute
periods

Figure 113. Alerts defined for the "Policy Options Retrieval System API"

10.4.4. Defining alerts for "Policy Holder Search Process API"

The C4E recommends that alerts for Process APIs should at least cover

• for all violations of API policies

• for all violations of QoS guarantees not captured in API policies

Applying this to the "Policy Holder Search Process API", referring to the NFRs and API policies
applicable to this API.

• "Throughput QoS guarantee exhausted for "Policy Holder Search Process API"": for violation
of Throttling API policy, severity Info, more than 60 violations for at least 3 consecutive 10-
minute periods
◦ Alerts when approx. 10% of 1-second intervals are above rate limit defined in the API
policy
• "Client not in Experience API or Process API subnet for "Policy Holder Search Process API"":
for violation of IP whitelist, severity Critical, more than 1 violation for at least 3 consecutive
1-minute periods
• "Response time QoS guarantee violated by "Policy Holder Search Process API"": for
violation of non-SLA-based QoS guarantee of 1100 requs/s, severity Warning, more than
6600 requests whose response time exceeds 100 ms for at least 3 consecutive 10-minute
periods
◦ Alerts when approx. 1% of API invocations (1% of 1100*60*10 = 6600) take longer
than 100 ms (twice the target median of 50 ms)

© 2017 MuleSoft Inc. 176

Anypoint Platform Architecture Application Network Design

◦ Note that exact QoS guarantee cannot be expressed in alert: median = 50 ms,
maximum = 150 ms

Figure 114. Alerts defined for the "Policy Holder Search Process API"

10.4.5. Alerts on API implementations augment alerts for API

invocations
Alerts on the level of API invocations and on the level of API implementations (i.e., the level of
individual application components) complement each other:

• If an API implementation crashes (and is not configured to be automatically restarted by

CloudHub) and no API client invokes that API then no alert on the level of API invocations is
raised - but alerts on the API implementation can be raised
◦ Can trigger alert when number API invocations falls below a threshold, but this risk
being triggered during periods of legitimately low activity
• Similar for consistently high CPU usage on the Mule runtime (CloudHub worker) to which an
API implementation is deployed
◦ Although this would typically also materialize as high response times on the level of API
invocations
• Deployment failures of an API implementation to a Mule runtime in the production and pre-
production environments should not occur and be covered by an alert

© 2017 MuleSoft Inc. 177

Anypoint Platform Architecture Application Network Design

Figure 115. Alerts defined for all API implementations executing on Mule runtimes, such as
CloudHub workers, complement alerts on the level of API invocations

10.5. Organizing discoverable documentation for

operations

10.5.1. Operations teams as a stakeholder in APIs

Some prominent organizations recommend that development teams should also operate the
APIs and API implementations they implement. If this advice is followed, then development
teams are at the same time operations teams. Regardless of whether this is the case or not,
operations teams are an important stakeholder in APIs.

The needs of operations teams are addressed by

• Dashboards and alerts in Anypoint Runtime Manager, Anypoint API Manager and Anypoint
Analytics
• Custom-written documentation:
◦ Runbooks, which are written for the on-call operations teams and must succinctly give
guidance on how to address alerts
◦ On-call registers, which identify the current on-call operations teams and are for anyone
who needs to contact them about an issue with "their" API, e.g., the operations team of
an API client of their API

In an application network, custom-written documentation for operations teams should be

discoverable through Anypoint Exchange.

© 2017 MuleSoft Inc. 178

Anypoint Platform Architecture Application Network Design

Also see [Ref11].

10.5.2. Linking discoverable documentation

The Acme Insurance C4E recommends that API documentation and assets be cross-linked as
follows to facilitate discovery and navigation, particularly for operations teams:

• The Anypoint Exchange entry for a particular version of an API specification links to the
matching
◦ API Portal
◦ Anypoint API Manager administration screens in all environments
◦ Anypoint Exchange entries for all known implementations of that API
• The Anypoint Exchange entry for a particular version of an API implementation (e.g., in the
form of a Mule application)
◦ links to the matching
▪ Anypoint Exchange entry for the API it implements
▪ Anypoint Exchange entries for all APIs it depends on (calls)
▪ Anypoint Runtime Manager dashboard for its deployments in all environments, e.g.,
to CloudHub
▪ GitHub repository
▪ CI/CD build pipelines, i.e., Jenkins jobs
◦ contains:
▪ Runbook
▪ which details resolution guidelines for all Anypoint API Manager and Anypoint
Runtime Manager alerts for this API implementation and the API it implements
▪ On-call register
▪ Developer onboarding documentation for developers joining the API implementation
development team

© 2017 MuleSoft Inc. 179

Anypoint Platform Architecture Application Network Design

Figure 116. The Anypoint Exchange entry for a particular version of an API specification links
to the matching API Portal, administration screen in Anypoint API Manager and to the Anypoint
Exchange entries for all known implementations of that API

Figure 117. The API Portal for the API linked-to from its Anypoint Exchange entry

Figure 118. The Anypoint API Manager administration screen for the API linked-to from its
Anypoint Exchange entry, showing summary API analytics

© 2017 MuleSoft Inc. 180

Anypoint Platform Architecture Application Network Design

Figure 119. The Anypoint Exchange entry for the API implementation Mule application linked-
to from the Anypoint Exchange entry of the API it exposes, linking to the Anypoint Exchange
entries for that API and all APIs it depends on (calls) plus the Anypoint Runtime Manager
dashboard for its CloudHub deployment. Also contains pages for the operations runbook and
on-call register and developer onboarding documentation and locates source code and CI/CD
build pipelines

© 2017 MuleSoft Inc. 181

Anypoint Platform Architecture Application Network Design

Figure 120. The Anypoint Runtime Manager dashboard for the CloudHub deployment of the
API implementation linked-to from its Anypoint Exchange entry

Summary
• Data used in monitoring, analysis and alerting flows from Mule runtimes to external
monitoring/analytics systems and/or Anypoint Platform, from where it is available via APIs
for external reporting
• Anypoint Platform collects numerous metrics for API invocations, such as response time,
payload size, client location, etc.
• For analysis in Anypoint Analytics metrics can be grouped by API, API client or any of the
other metrics
• Anypoint Platform supports analyses targeted specifically at API consumers and their API
clients
• In addition to interactive analyses, Anypoint Analytics supports custom charts and reports
• All analytics data can be downloaded in CSV files and/or retrieved through Anypoint
Platform APIs
• Alerts can be defined based on these API invocation metrics: request count and time,
response status code and number of violations of an API policy

© 2017 MuleSoft Inc. 182

Anypoint Platform Architecture Application Network Design

• Metrics for API implementations and alerts based on these metrics must be defined in
Anypoint Runtime Manager in addition to API invocations alerts
• Operations teams are an important stakeholder in API-related assets
• Structure and link Anypoint Exchange entries for APIs and API implementations, API
Portals, Anypoint API Manager administration screens and Anypoint Runtime Manager
dashboards to support operations teams

© 2017 MuleSoft Inc. 183

Anypoint Platform Architecture Application Network Design

Wrapping-Up Anypoint Platform Architecture:

Application Network Design

Objectives
• Review technology delivery capabilities
• Review OBD
• Review the course objectives
• Know where to go from here
• Being aware of the MuleSoft Certification program
• Take the class survey

Reviewing technology delivery capabilities

Review Figure 18 and confirm that all technology delivery capabilities needed in a context of
API-led connectivity and the application network are adequately provided by Anypoint
Platform.

Reviewing OBD
Review Figure 5 and briefly place all topics discussed in the course along one of the
dimensions of OBD.

Reviewing course objectives

Review Course goals and Course objectives from the start of the course and verify that goals
and objectives have been adequately addressed.

Knowing where to go from here

Take additional MuleSoft training courses

• Anypoint Platform Development:
◦ Fundamentals (4 days)
◦ Advanced (3 days)
◦ Advanced DataWeave (1 day)
◦ API Design (2 days)

© 2017 MuleSoft Inc. 184

Anypoint Platform Architecture Application Network Design

◦ Custom Connectors (1 day)

• Anypoint Platform Operations:
◦ Cloud Deployments (1 day)
◦ On-Prem Deployments (2 days)
◦ API Management (1 day)
• Anypoint Platform Architecture:
◦ Solution Design (4 days)

Learn and build on your own

• Read more
◦ Documentation: developer.mulesoft.com/docs
◦ Support knowledge base: support.mulesoft.com
◦ Blog: blogs.mulesoft.org/
◦ Mule in Action (2014) – Mule 3.4
• See more code
◦ Templates: www.mulesoft.com/exchange
• Report and track issues
◦ Mule kernel JIRA: www.mulesoft.org/jira/browse/MULE
◦ Mule: Submit through the support portal

Introducing the MuleSoft Certification program

MuleSoft Certification program

• Offers multiple types of professional accreditation for developers, architects, and partners
• Three levels of certification
• With each certification, you get
◦ A digital badge for your communications
◦ The ability to add the certification to your LinkedIn profile
◦ A free t-shirt

MuleSoft Certified Developer (MCD) and MuleSoft Certified

Architect (MCA) exams
• MCD - Integration and API Associate

© 2017 MuleSoft Inc. 185

Anypoint Platform Architecture Application Network Design

◦ First Level: Trained in Mule

◦ Recommended for students who have taken the Anypoint Platform Development:
Fundamentals class
• MCD - Integration Professional
◦ Second Level: Experienced in Mule
◦ Must show product and project experience
◦ Recommended for developers who have 6+ months work experience in Mule
• MCD - API Design Associate
• MCD - Connector Specialist
• MCA - Solution Design Specialist
• MCA - "to be announced"

Why take the exams?

• To obtain recognized industry certification
• To differentiate yourself in the marketplace
• Get a free t-shirt when you pass

Taking the class survey

Class survey
• You should have received an email with a link to the class survey
◦ Your instructor can also provide the direct link
▪ http://training.mulesoft.com/survey/<surveyID>.html
◦ Or you can go to a general page and select your class
▪ http://training.mulesoft.com/survey/survey.html
• Please fill the survey out now!
◦ We want your feedback!

© 2017 MuleSoft Inc. 186

Anypoint Platform Architecture Application Network Design

Appendix A: Documenting the Architecture Model

This section presents one concrete approach to documenting an architecture model by
arranging information and views (diagrams) for the various aspects of the architecture within a
particular framework and order. Taken together, this arrangement of information and views
characterizes and documents a given architecture model - such as that of Acme Insurance’s
application network at the stage discussed in this course - along different dimensions and for
different audiences. This is a well-established approach familiar from ArchiMate, TOGAF and
the like, although the viewpoints used here do not always rigorously follow those defined by
ArchiMate or TOGAF.

Following the focus of this course, this architecture documentation is mostly on the Enterprise
Architecture level, with elements of Solution Architecture, and is in-line with the dimensions of
OBD and the approaches of API-led connectivity and application networks.

The information and views collected here have all been produced for Acme Insurance during
the course: no new information or views are introduced here.

A.1. Architecture vision

A.1.1. Business outcomes dimension

Motivation: Figure 3

A.1.2. Platform dimension

Anypoint Platform capabilities: Figure 17, Figure 18

A.2. Business architecture

A.2.1. C4E dimension

1. Organization: Figure 23
2. Operational steering: Section 3.1.4

A.3. Application architecture

A.3.1. Business outcomes dimension

Requirements realization: Figure 36

© 2017 MuleSoft Inc. 187

Anypoint Platform Architecture Application Network Design

A.3.2. Platform and C4E dimension

All these application network-wide application architecture concerns are within

 the remit of the C4E and are mostly related to Anypoint Platform

Link to Developer Portal: Figure 50

APIs

This section documents the application architecture of APIs and API

implementations removed from the projects they were created in and the
 products they are used for. This is because API-related assets are application
network-scoped - despite being created and used in projects.

For each of the APIs in the application network

1. API data model design decision: Section 6.3.4, Section 6.3.11

2. End-to-end test scenarios: Section 9.2.6
3. Link to API designer API specification project: Figure 44
4. Link to API Anypoint Exchange entry: Figure 52, which in turn links to:
a. API Portal (incl. API Console and API Notebook): Figure 51
b. Anypoint API Manager administration screen: Figure 118
c. API implementation Anypoint Exchange entries: Figure 119
d. Anypoint Runtime Manager dashboards for API implementations: Figure 120
e. GitHub repository
f. CI/CD build pipelines

A.3.3. Projects dimension

For each project/product, e.g., "Aggregator Integration" product or

"Customer Self-Service App" product

1. Functional requirements: Section 4.1.1, Section 4.2.2

2. End-to-end API cooperation: Figure 38, Figure 54, Figure 55
3. Business alignment: Figure 42
4. Asynchronous API invocations: Figure 77
5. Concurrency considerations: Section 6.4.11

© 2017 MuleSoft Inc. 188

Anypoint Platform Architecture Application Network Design

6. Event and message exchanges: Figure 92, Figure 94

A.4. Technology architecture

A.4.1. Platform and C4E dimension

All these application network-wide technology architecture concerns are within

 the remit of the C4E and are mostly related to Anypoint Platform

1. Anypoint Platform deployment option: Figure 27, Figure 28, Figure 29, Figure 30, Figure 31
2. Anypoint Platform organizational setup: Section 3.3
3. Common API invocation dashboards and reports: Figure 110
4. Common application component alerts: Figure 115
5. DevOps guidelines: Section 9.1.2
6. Resilience testing guidelines: Section 9.2.4
7. API-related guidelines:
a. API policy enforcement guidelines: Section 5.3.5
b. API policy guidelines: Section 5.3.20, Section 5.3.21, Section 5.3.22
c. API versioning guidelines: Section 6.2.4
d. Alerting guidelines: Section 10.4.3, Section 10.4.4, Section 10.4.2

APIs

This section documents the technology architecture of APIs and API

 implementations removed from the projects they were created in and the
products they are used for.

For each of the APIs in the application network

1. API policy enforcement choice

2. API policies: Figure 67, Figure 68, Figure 69, Figure 70
3. Deployment architecture: Section 7.1.4
4. Approach to HA and scaling: Section 9.3.1
5. Failure mode analysis: Section 9.5.1
6. Persistence requirements and statefulness
7. Caching of exposed API: Section 6.4.8

© 2017 MuleSoft Inc. 189

 Anypoint Platform Architecture Application Network Design

8. Fault-tolerant API invocation strategies for each dependency: Section 7.2

9. Events and messages published and consumed, with destinations
10. Alerts: Figure 113, Figure 114, Figure 112

A.4.2. Projects dimension

For each project/product, e.g., "Aggregator Integration" product,

"Customer Self-Service App" product

1. Non-functional requirements: Section 5.1.1, Section 5.2.1, Section 5.2.3

2. Approach to meeting NFRs: Section 5.1.2, Section 5.2.2, Section 5.2.4
3. End-to-end API policy cooperation: Figure 71, Figure 72, Figure 73

© 2017 MuleSoft Inc. 190

Anypoint Platform Architecture Application Network Design

Appendix B: ArchiMate Notation Cheat Sheets

Relationships
Structural relationships

Parent composed of Child

Parent aggregates Child

assigned to

How realizes What

Dependency relationships

serves

Who
accesses write
Who accesses read Data
accesses read/write
Who

influences

Dynamic relationships

triggers

transfers to (flow)

Other relationships

Concrete spezialises Abstract

associated with

and

or

Figure 121. ArchiMate notation for relationships

Composite elements

Grouping Location

Figure 122. ArchiMate notation for composite elements

Motivation elements

Stakeholder Driver Assessment Goal Outcome

Principle Requirement Constraint Meaning Value

Figure 123. ArchiMate notation for motivation elements

© 2017 MuleSoft Inc. 191

Anypoint Platform Architecture Application Network Design

Strategy elements

Resource Capability Course of

Action

Figure 124. ArchiMate notation for strategy elements

Business layer elements

Active structure elements Behavior elements

Business Actor Business Role Business Business Business

Collaboration Process Function

Business Business Business

Interface Interaction Event

Business
Passive structure elements Service

Business Object Contract Representation

Composite elements

Product

Figure 125. ArchiMate notation for business layer elements

Application layer elements

Active structure elements Behavior elements

Application Application Application Application Application

Component Collaboration Interface Process Function

Application Application
Passive structure elements
Interaction Event

Data Object
Application
Service

Figure 126. ArchiMate notation for application layer elements

© 2017 MuleSoft Inc. 192

Anypoint Platform Architecture Application Network Design

Technology layer elements

Active structure elements Behavior elements

Device System Technology Technology

Node Software Process Function

Technology Technology Path Technology Technology

Collaboration Interface Interaction Event

Communication Network Technology

Service

Passive structure elements

Artifact

Figure 127. ArchiMate notation for technology layer elements

© 2017 MuleSoft Inc. 193

Anypoint Platform Architecture Application Network Design

Glossary
API
• Application Programming Interface
• A kind of application interface, i.e., a point of access to an application service
• to programmatic clients, i.e., API clients are typically application components
• using HTTP-based protocols, hence restricts the technology interfaces that may realize
this application interface to be HTTP-based
• typically with a well-defined business purpose, hence the application service to which
this application interface provides access typically realizes a business service
• See Figure 128
• Remarks:
◦ The prototypical API is a REST API using JSON-encoded data
◦ Non-programmatic interfaces, e.g., web UIs, are not APIs
▪ HTTP interfaces using HTML microdata are a corner case, as they are usable for
both human and programmatic clients
◦ Non-HTTP-based programmatic interfaces are not APIs
▪ E.g., Java RMI, CORBA/IIOP, raw TCP/IP interfaces not using HTTP
▪ Note that WebSocket interfaces are not APIs by this definition, and are not
currently supported by Anypoint Platform
◦ HTTP-based programmatic interfaces are APIs even if they don’t use REST or JSON
▪ E.g., REST APIs using XML-encoded data, JSON RPC, gRPC, SOAP/HTTP, XML/HTTP,
serialized Java objects over HTTP POST, …
▪ Note that interfaces using SSE (HTML5 Server-Sent Events) are APIs by this
definition, but are not currently supported by Anypoint Platform
◦ Interfaces using HTTP/2 are APIs. Also note that HTTP/2 adheres to HTTP/1.x
semantics
▪ E.g., gRPC
▪ But HTTP/2-based APIs are not currently supported by Anypoint Platform
• For instance:
◦ Auto policy rating API
▪ Is a programmatic application interface
▪ Is realized by these HTTP-based technology interfaces
▪ Auto policy rating JSON/REST programmatic interface

© 2017 MuleSoft Inc. 194

Anypoint Platform Architecture Application Network Design

▪ Auto policy rating SOAP programmatic interface

▪ Provides access to this application service: Auto policy rating
▪ which has well-defined business purpose because it
▪ realizes this business service: Auto policy rating
▪ serves this business service: Policy administration

Simplified notion of API

Business
Service

Application API
Service

API JSON REST SOAP API gRPC API

Implementation API

API Client

Figure 128. An API is primarily a programmatic application interface but the concept actually
combines aspects of Business Architecture, Application Architecture and Technology
Architecture

API client
• An application component
• that accesses a service
• by invoking an API of that service - by definition of the term API over HTTP
• See Figure 128

API consumer
• A business role, which is often assigned to an individual
• that develops API clients, i.e., performs the activities necessary for enabling an API
client to invoke APIs

API cross-cutting concern

© 2017 MuleSoft Inc. 195

Anypoint Platform Architecture Application Network Design

• Functionality that lends itself to implementation in an API policy

API definition
• Synonym for API specification, with API specification being the preferred term

API implementation
• An application component
• that implements the functionality
• exposed by the service
• which is made accessible via one or more APIs - by definition to API clients
• See Figure 128

API interface
• Synonym for API, with API being the preferred term
• Sometimes used in contexts where the simplified notion of API is the dominant one and
the interface-aspect of API needs to be addressed in contrast to the implementation-
aspect

API-led connectivity
• A style of integration architecture
• prioritizing APIs over other types of programmatic interfaces
• where each API is assigned to one of three tiers: System APIs, Process APIs and
Experience APIs

© 2017 MuleSoft Inc. 196

Anypoint Platform Architecture Application Network Design

Experience APIs

Aggregator
Quote Creation
API

create
Process APIs

Policy Holder Policy Options Motor Quote API

Search API Ranking API

System APIs

Motor Policy Home Policy Policy Options Motor Quote Motor Quote
Holder Search Holder Search Retrieval API Creation New Creation Addon
API API Business API Business API

Policy Admin
System

Figure 129. An example of the collaboration of APIs in the three tiers of API-led connectivity.
Note the use of the simplified notion of API in this diagram, as lower-level APIs are shown
serving higher-level APIs

API policy
• Defines a typically non-functional requirement
• that can be applied to an API (version)
• by injection into the API invocation between an API client and the API endpoint
• without changing the API implementation listening on that API endpoint
• Consists of API policy template (code) and API policy definition (data)
• For instance:
◦ Rate Limiting to 100 requs/s
◦ HTTP Basic Authentication enforcement using a given Identity Provider

API policy definition

• A concrete parameterization of a specific API policy
• by supplying values for all (required) parameters given in the API policy template for
that API policy
• that is therefore sufficient for applying that API policy to an API endpoint
• For instance:
◦ Rate Limiting to 100 requests per second

API endpoint
• The URL at which a specific API implementation listens for requests

© 2017 MuleSoft Inc. 197

Anypoint Platform Architecture Application Network Design

• and hence is available for access from API clients.

API policy enforcement

• The technology function that ensures an API policy definition is adhered-to
• Can either be realized by an API proxy or embedded within the API implementation
itself.

API policy template

• The code and configuration parameters (but not their values) that implement a specific
API policy
• Similar to a class in object-oriented programming
• For instance for Rate Limiting:
◦ The Mule application flow implementing the Rate Limiting functionality
◦ The declaration of the parameters for number of requests, time period and time unit

API provider
• A business role
• that develops, publishes and operates API implementations and all related assets

API proxy
• A dedicated node that enforces API policies
• by acting as an HTTP proxy between API client and the API implementation at a specific
API endpoint.
• API proxies need to be accessed explicitly by the API client in place of the "normal" API
implementation, via the same API.

API proxy endpoint

• The API endpoint on which a specific API proxy listens for requests.

API specification
• A formal, machine-readable definition of the technology interface of an API
• Sufficiently accurate for developing API clients and API implementations for that API
• For instance:
◦ RAML definition
◦ WSDL document
◦ OAS/Swagger specification

© 2017 MuleSoft Inc. 198

Anypoint Platform Architecture Application Network Design

Application (app)
• Used for API clients that are registered with Anypoint Platform as clients to at least one
API managed by Anypoint Platform
• In this context synonym for API client, with API client being the preferred term

Application interface
• Point of access to an Application Service
• exposing that Service to clients which may be humans or Application Components
• For instance:
◦ Auto policy rating programmatic interface
▪ Provides access to this Application Service: Auto policy rating
◦ Auto claim notification self-service UI
▪ Provides access to this Application Service: Auto claim notification
◦ Bank reconciliation batch interface
▪ Provides access to this Application Service: Bank reconciliation

Application
Service

Application Application
Programming User Interface
Interface

Application Application
Service Client Service Client

Figure 130. Business actor and application component accessing application service via
different application interfaces

Application network
• The state of an Enterprise Architecture
• emerging from the application of API-led connectivity
• that fosters governance, discoverability, consumability and reuse of the involved APIs
and related assets

© 2017 MuleSoft Inc. 199

Anypoint Platform Architecture Application Network Design

Figure 131. A visualization of the application network concept

Application service
• Exposes application functionality
• such as that performed by an Application Component
• through one or more application interfaces
• May (should) completely realize or at least serve a Business Service
• May serve other (more coarse-grained) Application Services
• For instance:
◦ Auto policy rating
▪ Realizes this Business Service: Auto policy rating
▪ Serves this Business Service: Policy administration
◦ Auto claim notification
▪ Serves this Business Service: Claim management
◦ Bank reconciliation
▪ Realizes this Business Service: Bank reconciliation

© 2017 MuleSoft Inc. 200

Anypoint Platform Architecture Application Network Design

Application Application Application

Component Service Interface

Figure 132. Application service

Business service
• Exposes business functionality
• such as that performed by a Business Actor
• through one or more business interfaces
• Has meaning and value on a business level
• May serve other (more coarse-grained) business services
• For instance:
◦ Policy administration
◦ Auto policy rating
▪ A fine-grained Business Service that serves the coarse-grained Business Service
Policy administration
◦ Claim management
◦ Bank reconciliation

Business Actor Business Business

Service Interface

Figure 133. Business service

Embedded API policy enforcement

• An implementation approach of API policy enforcement
• where this functionality is embedded in (co-located with) the API implementation
component
• rather than being isolated in a separate API proxy
• Recent versions of the Mule runtime provide this feature under the "API Gateway"
entitlement

CQRS
• Command Query Responsibility Segregation
• The usage of different models for reading from data (queries) and writing to data
(commands)

Event-Driven Architecture

© 2017 MuleSoft Inc. 201

Anypoint Platform Architecture Application Network Design

• An architectural style
• defined by the asynchronous exchange of events
• between application components.
• Hence a form of message-driven architecture
• where the exchanged messages are (or describe) events
• and the message exchange pattern is typically publish-subscribe (i.e., potentially many
consumers per event).

Event Sourcing
• An approach to data persistence that keeps persistent state as a series of events rather
than just a snapshot of the current state
• Often combined with CQRS

Interface
• Point of access to Service
• exposing that Service to Service clients
• Only if needed differentiate between business interfaces, application interface and
technology interface

RAML
• REST API Modeling Language
• YAML-based language for the machine- and human-readable definition of APIs that
embody most or all of the principles of REST, which are:
◦ Uniform interface, stateless, cacheable, client-server, layered system, code on
demand (optional)
◦ Adherency to the HTTP specification in its usage of HTTP methods, HTTP response
status codes, HTTP request and response headers, etc.

RAML definition
• An API specification expressed in RAML
• comprising one main RAML document
• and optional included
◦ RAML fragment documents
◦ XSD and JSON-Schema documents
◦ examples, etc.

© 2017 MuleSoft Inc. 202

Anypoint Platform Architecture Application Network Design

REST
• Representational State Transfer
• an architectural style characterized by the adherence to 6 constraints, namely
◦ Uniform interface
◦ Stateless
◦ Cacheable
◦ Client-server
◦ Layered system
◦ Code on demand (optional)

REST API
• An API that follows REST conventions
• and therefore adheres to the HTTP specification in its usage of HTTP methods, HTTP
response status codes, HTTP request and response headers, etc.

Service
• Explicitly defined exposed behavior
• exposes functionality to Service clients
• who access it through one or more interfaces
• Only if needed differentiate between Business Service, Application Service and
Technology Service
• May serve other (more coarse-grained) Services of the same kind
• For instance:
◦ Policy administration (a Business Service)
◦ Auto policy rating (an Application Service)
◦ HTTP request throttling (a Technology Service)

Services

Business Application Technology

Service Service Service

Figure 134. Services

Technology interface
• Point of access to a Technology Service
• May realize an application interface

© 2017 MuleSoft Inc. 203

Anypoint Platform Architecture Application Network Design

• Specifies data formats, parameter types, protocols, etc.

• For instance:
◦ Auto policy rating JSON/REST programmatic interface
▪ Realizes this application interface: Auto policy rating programmatic interface
◦ Auto policy rating SOAP programmatic interface
▪ Realizes this application interface: Auto policy rating programmatic interface
◦ Auto claim notification self-service web UI
▪ Realizes this application interface: Auto claim notification self-service UI
◦ Auto claim notification self-service mobile app UI
▪ Realizes this application interface: Auto claim notification self-service UI
◦ Bank reconciliation transaction file import
▪ Realizes this application interface: Bank reconciliation batch interface
◦ HTTP request throttling proxy endpoint
▪ Provides access to this Technology Service: HTTP request throttling

Technology Technology
Service Interface

Technology
Service Client

Figure 135. Application component accessing technology service via technology interface

Technology service
• Exposes technology functionality
• such as that performed by a Node or Device or System Software
• through one or more technology interfaces
• May serve Application Components
• May serve other (more coarse-grained) Technology Services
• For instance:
◦ Automatic restart
▪ Serves Application Components that must immediately resume operation after a
failure
◦ Persistent message exchange
▪ Serves Application Components that require guaranteed message delivery
◦ HTTP request throttling

© 2017 MuleSoft Inc. 204

Anypoint Platform Architecture Application Network Design

▪ Serves Application Components that expose services that must be protected from
request overload (DoS attacks)

Technology Technology
Node Service Interface

Figure 136. Technology service

Web Service
• Synonym for API, with API being the preferred term

© 2017 MuleSoft Inc. 205

Anypoint Platform Architecture Application Network Design

Bibliography
▪ [Ref1] MuleSoft, "Mule Runtime", https://docs.mulesoft.com/mule-user-guide. 2017.
▪ [Ref2] MuleSoft, "Design Center", https://docs.mulesoft.com/design-center. 2017.
▪ [Ref3] MuleSoft, "API Manager", https://docs.mulesoft.com/api-manager. 2017.
▪ [Ref4] MuleSoft, "Anypoint Exchange", https://docs.mulesoft.com/anypoint-exchange.
2017.
▪ [Ref5] MuleSoft, "Runtime Manager", https://docs.mulesoft.com/runtime-manager. 2017.
▪ [Ref6] MuleSoft, "Access Management", https://docs.mulesoft.com/access-management.
2017.
▪ [Ref7] MuleSoft, "Anypoint Analytics", https://docs.mulesoft.com/analytics. 2017.
▪ [Ref8] MuleSoft, "Anypoint MQ", https://docs.mulesoft.com/anypoint-mq. 2017.
▪ [Ref9] MuleSoft, "About Anypoint Platform Private Cloud Edition",
https://docs.mulesoft.com/anypoint-private-cloud. 2017.
▪ [Ref10] MuleSoft, "About Anypoint Platform for Pivotal Cloud Foundry",
https://docs.mulesoft.com/anypoint-platform-pcf/v/1.6. 2017.
▪ [Ref11] S.J. Fowler, Production-Ready Microservices. Sebastopol, CA: O’Reilly Media,
2016.
▪ [Ref12] M.T. Nygard, Release It!. Raleigh, NC: Pragmatic Bookshelf, 2007.
▪ [Ref13] V. Vernon, Domain-Driven Design Distilled. Boston, MA: Addison-Wesley, 2016.

© 2017 MuleSoft Inc. 206

Anypoint Platform Architecture Application Network Design

Version History
2017-11-01 v1.1 refinements to align with slides; improved Section 7.2;
updated Section 9.1.1; shortened Course objectives; updated
Section 7.1.4; added Bibliography; glossary now self-
contained; added Appendix A
2017-09-29 beta2 added missing queue to Figure 94; tier instead of layer for
API-led connectivity; added missing images; numerous little
refinements; improved layout
2017-09-06 beta for internal review
2017-08-27 alpha (v1.0) basis of first public delivery

© 2017 MuleSoft Inc. 207