Anypoint Platform

Architecture:
Application Networks
Student Manual

August 7, 2020

1
Table of Contents
Welcome To Anypoint Platform Architecture: Application Networks 1
1. Putting the Course in Context 7
2. Introducing MuleSoft, the Application Network Vision and Anypoint Platform 14
3. Establishing Organizational and Platform Foundations 32
4. Identifying, Reusing and Publishing APIs 61
5. Enforcing NFRs on the Level of API Invocations Using Anypoint API Manager 104
6. Designing Effective APIs 154
7. Architecting and Deploying Effective API Implementations 194
8. Augmenting API-Led Connectivity With Elements From Event-Driven Architecture 232
9. Transitioning Into Production 249
10. Monitoring and Analyzing the Behavior of the Application Network 273
Wrapping-Up Anypoint Platform Architecture: Application Networks 295
Appendix A: Documenting the Architecture Model 299
Appendix B: ArchiMate Notation Cheat Sheets 303
Glossary 306
Bibliography 318
Version History 320
Anypoint Platform Architecture Application Networks

Welcome To Anypoint Platform Architecture:

Application Networks

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 approach,
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

This course is predominantly about cloud-native architectures using the MuleSoft-hosted Anypoint
Platform, i.e., CloudHub.

Course outline
• Welcome To Anypoint Platform Architecture: Application Networks
• Module 1

© 2020 MuleSoft Inc. 1

Anypoint Platform Architecture Application Networks

• Module 2
• Module 3
• Module 4
• Module 5
• Module 6
• Module 7
• Module 8
• Module 9
• Module 10
• Wrapping-Up Anypoint Platform Architecture: Application Networks

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 (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.

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

© 2020 MuleSoft Inc. 2

Anypoint Platform Architecture Application Networks

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 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 materials and certification

Students receive the Course Manual (this document), a PDF of more than 200 pages, which
contains 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 Platform Architect For
students fulfilling the course’s prerequisites, attending class and studying the Course Manual should
be sufficient for passing the exam.

© 2020 MuleSoft Inc. 3

Anypoint Platform Architecture Application Networks

Introducing Acme Insurance

The Acme Insurance organization

Acme Insurance is a well-established, medium-sized, regional 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 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.

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 (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

© 2020 MuleSoft Inc. 4

Anypoint Platform Architecture Application Networks

• 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.

Beware of the two completely distinct meanings of the term "policy" in this course:
insurance policy on the one hand and API policy on the other hand. To avoid
 confusion, the latter will always be referred to using the complete term "API
policy".

Acme Insurance’s motivation to change

Under pressure from The New Owners, Acme Insurance executives embark on two immediate
strategic initiatives (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

© 2020 MuleSoft Inc. 5

Anypoint Platform Architecture Application Networks

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

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.

© 2020 MuleSoft Inc. 6

Anypoint Platform Architecture Application Networks

Module 1. Putting the Course in Context

Objectives
• Define Catalyst
• Describe how this course is aligned to parts of Catalyst
• Use essential course terminology correctly
• Recognize the ArchiMate 3 notation subset used in this course

© 2020 MuleSoft Inc. 7

Anypoint Platform Architecture Application Networks

1.1. Understanding the course organization

1.1.1. Introducing Catalyst

Catalyst (formerly known as OBD - Outcome-Based Delivery) 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

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

1.1.2. Course content in the context of Catalyst

Catalyst is materialized by "playbooks", where each playbook addresses one of the dimensions of
Catalyst and identifies activites along that dimension. This course is aligned with the principles of

© 2020 MuleSoft Inc. 8

Anypoint Platform Architecture Application Networks

Catalyst and the Catalyst 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 Catalyst:

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

• Organizational enablement through the C4E

However:

• Iteration is at the heart of Catalyst, 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
• Catalyst 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

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

© 2020 MuleSoft Inc. 9

Anypoint Platform Architecture Application Networks

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.

1.2.6. Simplified notion of API

In colloquial usage of the term API, departing from the precise - and somewhat confining -
definition given in 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 151

© 2020 MuleSoft Inc. 10

Anypoint Platform Architecture Application Networks

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
directly 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. Indeed, striving for a 1-to-1 relationship
between API as application interface and API implementation in particular is usually advisable as it
helps combat the complexity of large application networks. This is also the approach followed in
this course.

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 it is only the API implementation of the Process
API that depends on the technology interface of the System 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:

© 2020 MuleSoft Inc. 11

Anypoint Platform Architecture Application Networks

◦ 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 1.2.1.

1.2.7. Defining application network

See the corresponding glossary entry.

© 2020 MuleSoft Inc. 12

Anypoint Platform Architecture Application Networks

Summary
• Catalyst 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
• This course is aligned with the technology delivery and C4E dimensions of Catalyst
• An API is an application interface, typically with a business purpose, to programmatic API clients
using HTTP-based protocols
• Sometimes the term "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

© 2020 MuleSoft Inc. 13

Anypoint Platform Architecture Application Networks

Module 2. Introducing MuleSoft, the Application

Network Vision and Anypoint Platform

Objectives
• Articulate MuleSoft’s mission
• Explain MuleSoft’s proposal for closing the increasing IT delivery gap
• Describe the capabilities and high-level components of Anypoint Platform

© 2020 MuleSoft Inc. 14

Anypoint Platform Architecture Application Networks

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, MuleSoft’s founder, initiated 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 overview

• Company
◦ Founded in 2006, HQ: San Francisco
◦ Offices in 12 countries
◦ 1400+ employees worldwide
• Customers
◦ More than 1800 customers
◦ More than 175,000 developers worldwide
• 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

© 2020 MuleSoft Inc. 15

Anypoint Platform Architecture Application Networks

2.2. Introducing the application network vision

This module aims to give a simplified, easily understandable introduction to
concepts that will be developed and applied in much more detail and depth in the
remainder of this course - API-led connectivity and application networks. As such,
 this section contains a somewhat superficial comparison to SOA, does not make
use of the Acme Insurance case study and intentionally glosses over more subtle
but important aspects - which will be discussed in later course modules.

2.2.1. Traditional integration approaches can’t keep up

Every organization is undergoing change. This time of tremendous global challenges and continued
business transformation is putting the emphasis on digital businesses.

Companies are under greater pressure to deliver connected experiences, faster.

The reality is that most digital transformation initiatives are failing. Some of the reasons behind
these failures are:

• Legacy infrastructure is a barrier

• Data is siloed
• The pace of change is accelerating
• New regulations across countries and industries are being introduced on an ongoing basis

Figure 7. Traditional integration approaches can’t keep up

The complexity is massive and compounding, and the need for speed and agility is increasing.

Custom code is brittle, it breaks easily, it is the enemy of speed and agility and is also a bottleneck
because it is understood by too few people.

© 2020 MuleSoft Inc. 16

Anypoint Platform Architecture Application Networks

A better, more strategic approach to integration is needed in order to go faster and innovate at a
new scale, in a way that’s governed but not gated by IT.

MuleSoft is helping 1800+ enterprise customers undertake transformative changes, and so have a
unique perspective on the market.

2.2.2. IT capacity can’t keep pace with today’s demands

While IT delivery capacity remains nearly constant, the need to adopt to new technologies such as
cloud, SaaS, mobile, IoT, 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. Mordern businesses need a new approach

• Mordern businesses have composable building blocks, not a build from scratch approach
• IT should start providing capabilities and composite services that allow business to innovate
faster

© 2020 MuleSoft Inc. 17

Anypoint Platform Architecture Application Networks

Figure 9. In a composable enterprise, there is a standard way to unlock data and connect systems,
as opposed to integration being a secondary concern, leaving much more bandwidth for business
innovation.

2.2.5. IT’s role needs to change

MuleSoft proposes an IT operating model that puts IT in a more strategic position:

• Instead of IT focusing on delivering every single project itself, IT focuses on building reusable
assets that are specifically designed for consumption by a broader audience
• Not only does this free up precious time and resources, it significantly reduces the complexity
for IT to capitalize on new technologies
• It also frees up IT bandwidth to respond to the needs of the business to innovate – and,
importantly, meet the needs of the end-customer – much faster

Figure 10. 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.

© 2020 MuleSoft Inc. 18

Anypoint Platform Architecture Application Networks

2.2.6. New operating model emphasizes consumption

IT is now the steward of this operating model with a virtuous cycle in which IT develops, secures,
manages, maintains and automates core, system-level assets (such as access to data from various
systems), enabling the rest of the organization and external partners to innovate on top,
composing new products, services or experiences using the existing building blocks produced by IT.

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

• By emphasizing consumption and self-service, IT fundamentally increases speed, agility and

innovation at scale - in a future-proof, flexible and secure way
• Reusable assets enable developers to create services the business wants to consume
• By packaging those assets and best practices and publishing them in a marketplace so they’re
easy to find and easy to use – and by enforcing security and compliance standards every step of
the way – anyone across the organization, from app developers to line of business IT, can start
to self-serve and consume those approved assets to deliver their own projects

2.2.7. APIs as standard building blocks

In the proposed operating model, the organization packages-up core IT assets and capabilities as
APIs.

The 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.

• APIs adhere to standards (typically HTTP and REST), that are developer-friendly, easily
accessible and understood broadly
• They are treated more like products than code

© 2020 MuleSoft Inc. 19

Anypoint Platform Architecture Application Networks

• 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 12. Visualization of how APIs are the building blocks that represent unique business
capabilities and can be composed easily into a connected experience.

The best apps and companies of today are on this journey, taking an API-led approach to
connectivity and application development. The entire experience is composed of existing APIs, built
for reuse.

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 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.

© 2020 MuleSoft Inc. 20

Anypoint Platform Architecture Application Networks

Figure 13. 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. This approach democratizes innovation

The organizational approach to API-led connectivity empowers the entire organization to access
their best capabilities in delivering applications and projects through APIs that are developed by the
teams that are best equipped to do so due to their roles and knowledge of the systems they

© 2020 MuleSoft Inc. 21

Anypoint Platform Architecture Application Networks

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 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-user 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 14. 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 that encourages the

unlocking of assets and drives 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

© 2020 MuleSoft Inc. 22

Anypoint Platform Architecture Application Networks

2.2.10. Organize differently to drive API-led connectivity

Figure 15. A new mentality and operating model are needed. The C4E is a collaborative, cross-
functional team that acts as the steward of all assets. The team enables the broader organization
to consume those assets and get full value from them.

2.2.11. The application network emerges from the application

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

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".

© 2020 MuleSoft Inc. 23

Anypoint Platform Architecture Application Networks

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
◦ 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 Catalyst in 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.

© 2020 MuleSoft Inc. 24

Anypoint Platform Architecture Application Networks

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 16. 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 17 unpacks the technology delivery capabilities introduced at a high level in Figure 16.

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.

© 2020 MuleSoft Inc. 25

Anypoint Platform Architecture Application Networks

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 17. 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.

© 2020 MuleSoft Inc. 26

Anypoint Platform Architecture Application Networks

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
◦ Mule SDKs
◦ APIKit
◦ MUnit
• 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 Monitoring [Ref16]
◦ Anypoint Visualizer [Ref29]
• Anypoint Exchange: Save and share reusable assets publicly or privately [Ref4]. Preloaded
content includes:
◦ Anypoint Connectors
◦ Anypoint Templates
◦ Examples
◦ WSDLs
◦ RAML and OAS APIs
◦ Developer Portals
• Mule runtime and Runtime services: Enterprise-grade security, scalability, reliability and high
availability:
◦ Mule runtime [Ref1]
◦ Anypoint MQ [Ref8]

© 2020 MuleSoft Inc. 27

Anypoint Platform Architecture Application Networks

◦ Object Store
◦ Anypoint Virtual Private Cloud (VPC)
◦ CloudHub
◦ Anypoint Runtime Fabric [Ref27]
◦ Anypoint Connectors:
▪ Connectivity to external systems
▪ Dynamic connectivity to APIs
▪ Build custom connectors using Mule SDKs
• Anypoint Security
• Anypoint Platform Private Cloud Edition
• Government Cloud [Ref28]

Figure 18. Anypoint Platform and its main components.

© 2020 MuleSoft Inc. 28

Anypoint Platform Architecture Application Networks

Figure 19. 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 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 enable 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 user-friendly interactive layer on top of

Anypoint Platform APIs
• Mule Maven Plugin, a Maven plugin automating packaging and deployment of Mule applications
(including API implementations) to all kinds of Mule runtimes, typically used in CI/CD (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).

2.4.3. Understanding audit logging on Anypoint Platform

Anypoint Platform maintains an audit log of all changes made to an Anypoint Platform organization,
recording, amongst other data,

© 2020 MuleSoft Inc. 29

Anypoint Platform Architecture Application Networks

• the timestamp of the change,

• the Anypoint Platform user who made the change (subject),
• the affected Anypoint Platform object, and
• the action performed by the user (verb).

As a general rule, all actions of type create/update/delete are recorded in the audit log, but
concrete actions for each type of action are much more specific than this. For example, when
updating (editing) an API version (object), the audit log distinguishes between actions like adding a
tag, removing a tag, editing the name of the API version, and many more.

The audit log can be retrieved and queried via the Anypoint Platform web UI and an Anypoint
Platform API by users with the appropriate authorization.

The retention period of audit logs in Anypoint Platform is six years.

© 2020 MuleSoft Inc. 30

Anypoint Platform Architecture Application Networks

Summary
• MuleSoft’s mission is "To connect the world’s applications, data and devices to transform
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 consumption, 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 & services
• Interaction with Anypoint Platform can be extensively automated
• Anypoint Platform maintains an audit log of all changes to an Anypoint Platform organization

© 2020 MuleSoft Inc. 31

Anypoint Platform Architecture Application Networks

Module 3. Establishing Organizational and

Platform Foundations

Objectives
• Advise on establishing a C4E and identify KPIs to measure its success
• Choose between options for hosting Anypoint Platform and provisioning Mule runtimes
• Describe the set-up of organizational structure on Anypoint Platform
• Compare and contrast Identity Management and Client Management on Anypoint Platform

© 2020 MuleSoft Inc. 32

Anypoint Platform Architecture Application Networks

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 is 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

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

© 2020 MuleSoft Inc. 33

Anypoint Platform Architecture Application Networks

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 for the C4E: see 1.1.1
• 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

The following technical business roles are assigned to the C4E at the positions in their
organizational structure as shown in Figure 20:

• Platform Architect:
◦ Responsibilities: Platform vision and it’s evolution to meet tactical and strategic objectives of
the business
◦ Profile: Solid understanding of the technical foundation of the platform; a technology
enthusiast with a strong track record of building and running high volume, reliable
architectures, preferably including cloud, As-A-Service infrastructure and applications
• API Architect; Integration Architect/Developer:
◦ Responsibilities: Provides “enough” guidance over the design and operations of the C4E
assets; thought leadership, leading key stakeholders in designing and adopting API
architectures; architecting integrations solutions for C4E internal customers working close
with them through the whole lifecycle; gathering requirements from both the business and
technical teams to determine the integration solutions/APIs
◦ Profile: Deep experience of integration and API architecture, thorough understanding of
industry trends, vendors, frameworks and practices
• DevOps Architect/Engineer

© 2020 MuleSoft Inc. 34

Anypoint Platform Architecture Application Networks

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 20. Organizational view into Acme Insurance’s target Business Architecture with a C4E
supporting LoBs and their project teams with their integration needs. Technical C4E business roles
are shown in blue, managerial C4E business roles are not shown.

© 2020 MuleSoft Inc. 35

Anypoint Platform Architecture Application Networks

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 vision is being
realized
3. From the above lists, extract a list of corresponding metrics

© 2020 MuleSoft Inc. 36

Anypoint Platform Architecture Application Networks

Solution

See 3.1.4.

© 2020 MuleSoft Inc. 37

Anypoint Platform Architecture Application Networks

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.

The extraction of many of these metrics can be automatically through the invocation of Anypoint
Platform APIs:

• # of assets published to Anypoint Exchange at organization or business group level

• # of interactions with Anypoint Exchange assets in a given period
• # of APIs managed by Anypoint Platform, overall, in production, per business group, …
• # of API clients registered for access to APIs
• # of reused assets (fragments, connectors, APIs etc) per month/year trend
• # of API implementations deployed to Anypoint Platform
• # of API invocations in a given period
• # or fraction of lines of code covered by automated tests in CI/CD pipelines
• # of automated scripts, reusable templates, … improving developer experience
• # or sum of alerts, production defects, total uptime, … measuring operational outcomes
• Fraction of API invocations that return HTTP 5xx responses
• Time to market (duration from specification to production deployment)

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

© 2020 MuleSoft Inc. 38

Anypoint Platform Architecture Application Networks

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

© 2020 MuleSoft Inc. 39

Anypoint Platform Architecture Application Networks

3.2. Understanding Anypoint Platform deployment

scenarios

3.2.1. Separating Anypoint Platform control plane and runtime

plane
Anypoint Platform components (2.4.1) can be distinguished according to whether they are directly
involved in the execution of Mule applications or not:

• The Anypoint Platform runtime plane comprises the Mule runtime itself, Anypoint Connectors
used by Mule applications executing in the Mule runtime, and all supporting Runtime services,
incl. Anypoint Enterprise Security, Anypoint Fabric, Anypoint VPCs, CloudHub Dedicated Load
Balancers, Object Store and Anypoint MQ. Simply put, the runtime plane is where integration
logic executes.
• The Anypoint Platform control plane comprises all Anypoint Platform components that are
involved in managing/controlling the components of the runtime plane (i.e., Anypoint
Management Center, incl. Anypoint API Manager and Anypoint Runtime Manager), the design of
APIs or Mule applications (i.e., Anypoint Design Center, incl. Anypoint Studio and API designer)
or the documentation and discovery of application network assets (i.e., Anypoint Exchange)

Figure 23. Components of the Anypoint Platform belong to either the control plane or the runtime
plane.

In addition to executing integration logic implemented in terms of Mule applications in the Anypoint
Platform runtime plane, the Anypoint Platform also supports API management and analytics of APIs
implemented not as Mule applications and therefore executing outside the Anypoint Platform
runtime plane - so-called external API implementations. These approaches make use of relevant
components of the Anypoint Platform control plane, such as Anypoint API Manager. See Module 5.

© 2020 MuleSoft Inc. 40

Anypoint Platform Architecture Application Networks

3.2.2. Introducing MuleSoft-hosted and customer-hosted

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

Figure 24. Overview of Anypoint Platform deployment options and MuleSoft product names (in
bold) for each supported scenario.

Options for the deployment of the Anypoint Platform control plane:

• MuleSoft-hosted:
◦ Product: Anypoint Platform
◦ AWS regions: US East (N Virginia, https://anypoint.mulesoft.com) or EU (Frankfurt,
https://eu1.anypoint.mulesoft.com)
• Customer-hosted:
◦ Product: Anypoint Platform Private Cloud Edition

Options for the deployment of the Anypoint Platform runtime plane, incl. provisioning of Mule
runtimes:

• MuleSoft-hosted:
◦ In the public AWS cloud: CloudHub
◦ In an AWS VPC: CloudHub with Anypoint VPC
◦ AWS regions:
▪ Under management of the US East control plane: US East, US West, Canada, Asia Pacific,
EU (Frankfurt, Ireland, London, …), South America
▪ Under management of the EU control plane: EU (Frankfurt and Ireland)
• Customer-hosted:
◦ Manually provisioned Mule runtimes on bare metal, VMs, on-premises, in a public or private
cloud, …

© 2020 MuleSoft Inc. 41

Anypoint Platform Architecture Application Networks

◦ iPaaS-provisioned Mule runtimes:

▪ MuleSoft-provided software appliance: Anypoint Runtime Fabric
▪ Customer-managed Pivotal Cloud Foundry installation: Anypoint Platform for Pivotal Cloud
Foundry

3.2.3. MuleSoft-hosted Anypoint Platform control plane and

runtime plane with iPaaS functionality in public cloud

Figure 25. MuleSoft-hosted Anypoint Platform control plane managing MuleSoft-hosted Anypoint
Platform runtime plane. Runtime plane comprises iPaaS-provisioned Mule runtimes on CloudHub in
the public AWS cloud.

3.2.4. MuleSoft-hosted Anypoint Platform control plane and

runtime plane with iPaaS functionality in Anypoint VPC

© 2020 MuleSoft Inc. 42

Anypoint Platform Architecture Application Networks

Figure 26. MuleSoft-hosted Anypoint Platform control plane managing MuleSoft-hosted Anypoint
Platform runtime plane. Runtime plane comprises iPaaS-provisioned Mule runtimes on CloudHub in
an Anypoint VPC.

3.2.5. MuleSoft-hosted Anypoint Platform control plane and

customer-hosted runtime plane without iPaaS functionality

© 2020 MuleSoft Inc. 43

Anypoint Platform Architecture Application Networks

Figure 27. MuleSoft-hosted Anypoint Platform control plane managing customer-hosted Anypoint
Platform runtime plane. Runtime plane comprises manually provisioned Mule runtimes.

3.2.6. MuleSoft-hosted Anypoint Platform control plane and

customer-hosted runtime plane with iPaaS functionality on
Anypoint Runtime Fabric
Anypoint Runtime Fabric is a software appliance that provides customer-hosted iPaaS functionality
comparable to CloudHub. It leverages a Kubernetes cluster to do so, and executes Mule
applications on Mule runtimes within Docker containers.

Anypoint Runtime Fabric:

• Is MuleSoft-provided but customer-managed, currently supported on bare metal, VMs, AWS,

Azure
• Contains and requires its own dedicated Docker and Kubernetes installations and infrastructure
• Connects to a MuleSoft-hosted control plane and integrates with Anypoint Runtime Manager for
one specific environment
• Connection to control plane is via AMQP/TLS initiated by Anypoint Runtime Fabric
• Follows iPaaS model similar to CloudHub: one Mule application deployed via Anypoint Runtime
Manager to its own Mule runtime and its own "machine" (VM or pod/container)
• Contains a load-balancer for HTTP traffic to replicated Mule applications (performs TLS
termination)

© 2020 MuleSoft Inc. 44

Anypoint Platform Architecture Application Networks

• Leverages Kubernetes Secrets for Mule runtime license, certificates, etc.

Figure 28. MuleSoft-hosted Anypoint Platform control plane managing customer-hosted Anypoint
Platform runtime plane. Runtime plane comprises iPaaS-provisioned Mule runtimes on a Kubernetes
cluster maintained by Anypoint Runtime Fabric.

3.2.7. Customer-hosted Anypoint Platform control plane and

runtime plane without iPaaS functionality

© 2020 MuleSoft Inc. 45

Anypoint Platform Architecture Application Networks

Figure 29. Anypoint Platform Private Cloud Edition: Customer-hosted Anypoint Platform control
plane managing customer-hosted Anypoint Platform runtime plane. Runtime plane comprises
manually provisioned Mule runtimes.

3.2.8. Customer-hosted Anypoint Platform control plane and

runtime plane with iPaaS functionality on Pivotal Cloud Foundry

© 2020 MuleSoft Inc. 46

Anypoint Platform Architecture Application Networks

Figure 30. Anypoint Platform for Pivotal Cloud Foundry: Customer-hosted Anypoint Platform control
plane managing customer-hosted Anypoint Platform runtime plane. Runtime plane comprises
iPaaS-provisioned Mule runtimes on PCF.

3.2.9. 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, CloudHub Hybrid Anypoint Anypoint Anypoint

Feature Runtime Platform Platform for
Fabric Private Cloud Pivotal Cloud
Edition Foundry

API designer yes yes yes yes yes

Flow designer yes yes yes no no

© 2020 MuleSoft Inc. 47

Anypoint Platform Architecture Application Networks

Component, CloudHub Hybrid Anypoint Anypoint Anypoint

Feature Runtime Platform Platform for
Fabric Private Cloud Pivotal Cloud
Edition Foundry

Anypoint yes yes yes yes yes

Access
Management

LDAP for no no no yes yes

Identity
Management

Anypoint yes yes yes yes yes

Runtime
Manager

External no yes yes yes yes

Runtime
Analytics

Schedules UI yes yes no yes yes

Anypoint yes yes no no no

Runtime
Manager
monitoring
dashboards

Logs in yes no no no? no?

Anypoint
Runtime
Manager

Insight yes yes no no no

Anypoint yes yes no no no

Runtime
Manager alerts

Anypoint API yes yes yes yes yes

Manager

Anypoint API yes yes yes no no

Manager alerts

Anypoint yes yes yes no no

Analytics

© 2020 MuleSoft Inc. 48

Anypoint Platform Architecture Application Networks

Component, CloudHub Hybrid Anypoint Anypoint Anypoint

Feature Runtime Platform Platform for
Fabric Private Cloud Pivotal Cloud
Edition Foundry

External API no yes yes yes yes

Analytics

Anypoint yes yes yes yes yes

Exchange

Anypoint MQ yes no no no no

iPaaS yes no yes no yes

Mule runtime yes no yes no yes

load balancing

Mule runtime yes yes yes yes yes

persistent VM
queues

Mule runtime yes no yes no yes

auto-restart

Mule runtime no yes yes yes yes

cluster

Zero downtime yes no yes no yes

deployments

Notes:

• External Analytics refers to Splunk, ELK or similar software. Normally, external Analytics for API
and runtime metrics is configured, when supported, through Anypoint Runtime Manager. In
Anypoint Runtime Fabric though this is configured differently, without Anypoint Runtime
Manager, by forwarding Kubernetes cluster logs to the external Analytics 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 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, Anypoint Runtime
Fabric’s or PCF’s sophisticated 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

© 2020 MuleSoft Inc. 49

Anypoint Platform Architecture Application Networks

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.

© 2020 MuleSoft Inc. 50

Anypoint Platform Architecture Application Networks

3.2.10. Exercise 2: Choosing between deployment scenarios

Reflecting on the various deployment scenarios supported by Anypoint Platform:

1. Discuss the characteristics of each scenarios

2. For each deployment scenario, identify requirements that would clearly require that scenario

© 2020 MuleSoft Inc. 51

Anypoint Platform Architecture Application Networks

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
• IT operations effort: favors MuleSoft-hosted Anypoint Platform over all other deployment
scenarios; favors Anypoint Runtime Fabric over 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 Runtime Fabric, Anypoint
Platform Private Cloud Edition and Anypoint Platform for Pivotal Cloud Foundry over CloudHub
with geographically close runtime plane
• Isolation between Mule applications: favors scenarios where each Mule application is assigned to
its own Mule runtime; favors bare metal over VMs over containers for Mule runtimes
• 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
• Scalability of runtime plane: consider horizontal and vertical scaling; consider static and
dynamic (load-based, automatic) scaling; favors cloud-deployments of runtime plane, including
CloudHub; favors iPaaS functionality over manually provisioned Mule runtimes
• Roll-out of new releases: continuously (weekly) in the MuleSoft-hosted control plane versus
quarterly releases of Anypoint Platform Private Cloud Edition

© 2020 MuleSoft Inc. 52

Anypoint Platform Architecture Application Networks

3.2.11. Anypoint Platform data residency

The deployment scenarios supported by Anypoint Platform cover a large number of options of who
(MuleSoft or the customer) controls and manages the various components of Anypoint Platform,
where these components reside, and where Mule applications execute as a result. As Mule
applications execute integration logic, data flows through the various systems of Anypoint Platform
and beyond. This section describes in detail where what kind of data is sent and stored. This is
particularly relevant in the light of various regulatory (legal) requirements such GDPR
(https://www.eugdpr.org) and the Patriot Act.

Figure 31. AWS regions in which MuleSoft hosts the Anypoint Platform control plane (large colored
circles) and runtime plane (small yellow marks). Data resides within the runtime plane, while
limited amounts of metadata are sent from there to the managing control plane (arrows in the
color of the managing control plane).

The fundamental principle is that the location of Mule runtimes, together with the integration logic
implemented by Mule applications executing in these Mule runtimes, determine the location and
residency of all data. In addition to the data itself, limited amounts of metadata and metrics are
exchanged with the Anypoint Management Center components of the Anypoint Platform control
plane. Specifically:

• Mule runtimes and Mule applications can either be managed entirely by the customer or execute
in one of the AWS regions supported by CloudHub as described in 3.2.2: this determines where
all data, in the form of Mule messages, is processed.
• Mule applications can make use of Object Store, persistent VM queues or other resilience
features. In a CloudHub deployment, all of these features store data in the same AWS region as
the Mule runtime itself. For customer-managed deployments the customer fully controls where

© 2020 MuleSoft Inc. 53

Anypoint Platform Architecture Application Networks

Mule applications send or store data.

• Mule applications may also make use of Anypoint MQ (8.3.1): Anypoint MQ queues/exchanges
are explicitly created to reside in an AWS region. The available regions are typically those of the
Anypoint Platform runtime plane.
• Metadata, incl. metrics, about Mule messages and API invocations is sent by the Mule runtime to
Anypoint Management Center (10.3.1). Thus by selecting either a customer-hosted control
plane, or one of the supported AWS regions of the MuleSoft-hosted Anypoint Platform (3.2.2),
customers determine where this metadata is sent.
◦ Example of metadata: CPU/memory usage, message/error count, API name and version,
geodata about the API client, HTTP method, violated API policy name, etc. (10.4.1)
• Logs produced by Mule applications deployed to CloudHub have residency characteristics
similarly to those of metadata.
• Mule applications may produce business events and Anypoint Runtime Manager may use the
Insight feature to analyze and replay business events. Depending on the details of the
configuration, events may also include the data (payload) of the Mule message, although this is
not the case by default. If this feature is chosen, then message data (and not just metadata) is
sent to Anypoint Runtime Manager.
• Mule applications are typically deployed to Mule runtimes using Anypoint Runtime Manager: this
means that the Mule applications themselves, incl. all code and resources packaged within the
Mule applications, are stored where the Anypoint Platform control plane resides.

These rules are typically applied as follows to meet regulatory requirements through jurisdiction-
local deployments (assuming suitably implemented Mule applications):

• A combination of the MuleSoft-hosted Anypoint Platform EU/US control plane and a matching
MuleSoft-hosted EU/US runtime plane (i.e., using CloudHub and Anypoint MQ in a matching
AWS region) keeps all data and metadata in the EU/US.
• A combination of the MuleSoft-hosted Anypoint Platform EU/US control plane and a customer-
hosted runtime plane (i.e., Hybrid deployment , optionally with Anypoint Runtime Fabric) keeps
all data on customer-hosted infrastructure and all metadata in the EU/US.
• A combination of a customer-hosted Anypoint Platform control plane and a matching customer-
hosted runtime plane (i.e., using Anypoint Platform Private Cloud Edition or Anypoint Platform
for Pivotal Cloud Foundry) keeps all data and metadata on customer-hosted infrastructure.

© 2020 MuleSoft Inc. 54

Anypoint Platform Architecture Application Networks

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 32. Anypoint Access Management and the Anypoint Platform entitlements.

© 2020 MuleSoft Inc. 55

Anypoint Platform Architecture Application Networks

Figure 33. 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 34. 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

© 2020 MuleSoft Inc. 56

Anypoint Platform Architecture Application Networks

◦ enables Single Sign-On (SSO)

• Client Management is concerned with APIs managed by Anypoint Platform, and primarily with
those using OAuth 2.0 to authenticate and authorize API clients
◦ See below for a more nuanced discussion of Client Management

Both Identity Management and Client Management require an Identity Provider. Somewhat
simplifying the roles and responsibilities of an Identity Provider in both cases, one could say:

• The Identity Provider for Identity Management stores and validates user credentials.
• The Identity Provider for Client Management issues, stores, and validates OAuth 2.0 access
tokens for API clients.

By default, Anypoint Platform acts as an internal Identity Provider for Identity Management.
Anypoint Platform also supports configuring one external Identity Provider for Identity Management
at the Anypoint Platform organization level.

If an external Identity Provider is configured for Identity Management, then SAML 2.0 bearer
tokens issued by that Identity Provider can be used for invocations of the Anypoint Platform APIs.
Optionally, before configuring an external Identity Provider for Identity Management, administrative
users can be set up for invoking the Anypoint Platform APIs. These will remain valid after the
external Identity Provider has been configured and the credentials of these users can therefore still
be used to invoke Anypoint Platform APIs after the external Identity Provider has been configured
for Identity Management.

By default, Anypoint Platform does not act as an Identity Provider for OAuth 2.0 Client
Management. This means that in order for APIs managed by Anypoint Platform to make use of
OAuth 2.0, an external Identity Provider must be configured.

Anypoint Platform supports the configuration of multipe Identity Providers for Client Management.
All Identity Providers for Client Management must be configured at the Anypoint Platform
organization level and can then be assigned to individual business groups and environments. This
allows using different Identity Providers for - and therefore segregating Client Management and API
clients by:

• Different organizational units (mapped to business groups)

• Different software development phases (production, testing, development, etc., mapped to
environments)
• Internal and external APIs and API clients

There is a limited form of Client Management that is unrelated to OAuth 2.0, and is represented,
for example, by the checks performed by the Client ID enforcement API policy (see 5.3.27). In this
form of Client Management, no tokens are involved and API clients are simply identified and

© 2020 MuleSoft Inc. 57

Anypoint Platform Architecture Application Networks

authenticated by client ID and secret. For this limited, non-OAuth 2.0 form of Client Management,
Anypoint Platform does act as an internal Identity Provider if no external Identity Provider has been
configured for Client Management. Once an Identity Provider has been configured for Client
Management, and hence the full OAuth 2.0 form of Client Management becomes available, that
Identity Provider then is invovled in all forms of Client Management, including the limited, non-
OAuth 2.0 form of Client Management - although the Client Management performed in Anypoint
Platform continues to remain authoritative for the non-OAuth 2.0 form of Client Management (see
5.3.16).

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 Salesforce Identity, 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
• OpenID Connect (OIDC) Dynamic Client Registration (DCR)
◦ a standard implemented by Identity Providers such as Salesforce Identity, Okta, and OpenAM

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 ontop
of AD. They configure their Anypoint Platform organization in the MuleSoft-hosted Anypoint

© 2020 MuleSoft Inc. 58

Anypoint Platform Architecture Application Networks

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.

© 2020 MuleSoft Inc. 59

Anypoint Platform Architecture Application Networks

Summary
• A federated C4E is established at Acme Insurance 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 control plane and runtime plane can both be hosted by MuleSoft or customers
• Mule runtimes can be provisioned manually or through iPaaS functionality
• iPaaS-provisioning of Mule runtimes is supported via CloudHub, Anypoint Platform for Pivotal
Cloud Foundry and Anypoint Runtime Fabric
• 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

© 2020 MuleSoft Inc. 60

Anypoint Platform Architecture Application Networks

Module 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
• Reason in detail composition and collaboration of APIs
• Reuse APIs wherever possible
• Publish APIs and related assets for reuse
• Understand how Anypoint API Community Manager helps build developer communities around
some or all APIs in an application network

© 2020 MuleSoft Inc. 61

Anypoint Platform Architecture Application Networks

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 (Acme Insurance’s motivation to change):

• Open-up to Aggregators for motor insurance

• Provide self-service capabilities to customers

All relevant stakeholders come together under the guidance of the C4E 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.

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 35. Architecturally significant features of the immediately relevant strategic initiatives, and
the products they are assigned to.

The "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

© 2020 MuleSoft Inc. 62

Anypoint Platform Architecture Application Networks

application network.

© 2020 MuleSoft Inc. 63

Anypoint Platform Architecture Application Networks

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 (Figure 35).

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 (3.1.2). In particular, the
C4E’s Platform Architect spends 50% of his time contributing exclusively to this project, and an
experienced architect from the Personal Motor LoB who is assigned full-time to this project also
reports to the C4E Lead in his new role of C4E API Architect.

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 5.1, for the non-functional requirements of this feature.

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, fully-automated 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 most likely to be attractive to the customer and,
at the same time, 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

© 2020 MuleSoft Inc. 64

Anypoint Platform Architecture Application Networks

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 36. 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: 5.1.1.

© 2020 MuleSoft Inc. 65

Anypoint Platform Architecture Application Networks

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 (Figure 2), 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"

◦ 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 can be in-front of the same backend system
◦ Change comparatively rarely as backend systems change rarely

© 2020 MuleSoft Inc. 66

Anypoint Platform Architecture Application Networks

Solution

The following APIs could serve to realize the functional requirements of the "Create quote for
aggregators" feature with an API-led connectivity approach (Figure 37):

• "Aggregator Quote Creation EAPI": (Aggregator policy description) -> (0-5 ranked motor policy
quotes)
◦ Receives a description of the details of the motor policy desired by the customer, incl.
essential customer data, as specified by the Aggregator. Returns up to 5 matching quotes,
ranked (ordered) such that the most preferred quote is first
◦ Determines whether the customer is an existing policy holder or new to Acme Insurance
◦ Retrieves a ranked list of policy options to be offered
◦ Creates one quote for each of the top 5 policy options and returns these, as specified by the
Aggregator
• "Policy Holder Search PAPI": (personal identifiers) -> (matching policy holders)
◦ Based on personal identifiers (name, dob, SSN, …) returns a description of all matching policy
holders of any policies at Acme Insurance, for any LoB
• "Policy Options Ranking PAPI": (policy holder properties, policy properties) -> (policy options
ranked from highest to lowest)
◦ Given essential properties of a (future) policy holder (age, standing with Acme Insurance, …)
and a some aspects of the policy to be offered to that policy holder (type of vehicle/home,
value, …) retrieves a list of available options for this policy (collision coverage, liability
coverage, comprehensive insurance, theft, …) and ranks them in the order in which they
should be offered
• "Motor Quote PAPI": create: (policy description, policy holder description) -> (motor policy
quote)
◦ Given a complete description of a desired motor policy and the (future) policy holder, creates
a matching quote and returns its description
• "Motor Policy Holder Search SAPI": (personal identifiers) -> (matching motor policy holders)
◦ Searches the Policy Admin System for policy holders of motor policies matching the given
personal identifiers (name, dob, SSN, …) and returns matching policy holder’s data
• "Home Policy Holder Search SAPI": (personal identifiers) -> (matching home policy holders)
◦ Searches the Policy Admin System for policy holders of home policies matching the given
personal identifiers (name, dob, SSN, …) and returns matching policy holder’s data
• "Policy Options Retrieval SAPI": (policy properties) -> (policy options)
◦ Given some aspects of a policy to be created (type of vehicle/home, value, …) returns all
options that can possibly be offered for this policy (collision coverage, liability coverage,
comprehensive insurance, theft, …)

© 2020 MuleSoft Inc. 67

Anypoint Platform Architecture Application Networks

• "Motor Quote Creation New Business SAPI": (policy description, policy holder description) ->
(new business motor policy quote)
◦ Given a complete description of a desired motor policy and a future policy holder new to
Acme Insurance, creates a "new business" quote for such a motor policy and returns its
description
• "Motor Quote Creation Addon Business SAPI": (policy description, policy holder identifier) ->
(addon business motor policy quote)
◦ Given a complete description of a desired motor policy and an identifier for an existing policy
holder, creates an "addon business" quote for such a motor policy and returns its description

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 37. 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 EAPI" which in turn triggers apparently
synchronous invocations of several APIs in the other 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 are
discussed.

© 2020 MuleSoft Inc. 68

Anypoint Platform Architecture Application Networks

Summary

• Essential aspect of "Create quote for aggregators" feature implemented by one synchronous
invocation of the "Aggregator Quote Creation EAPI"
• In turn triggers invocations of several APIs in all 3 tiers of the architecture
• Ultimately leads to invocations of the Policy Admin System

© 2020 MuleSoft Inc. 69

Anypoint Platform Architecture Application Networks

4.2.5. Exercise 4: Pros and cons of fine-grained APIs and API

implementations
Figure 37 is an example of a pronouncedly fine-grained API architecture. A break-down of the same
functionality (that of the "Create quote for aggregators" feature) into much more coarse-grained
APIs is equally possible:

• Compare and contrast coarse-grained and fine-grained APIs and API implementations

© 2020 MuleSoft Inc. 70

Anypoint Platform Architecture Application Networks

Solution

The granularity of the decomposition of functionality into APIs and API implementations can be
analyzed along the following dimensions:

• Deployability: Each API and API implementation is independently deployable from all other APIs
and API implementations (assuming proper version management (6.2) to not break API
dependencies): finer-grained APIs and API implementations allow finer-grained evolution and
rollout of functionality (in the form of newer versions of APIs and API implementations)
• Management: Each API implementation and API is monitored and managed independently,
where the latter includes the enforcement of access control, QoS, etc. (Module 5), which can
hence be more finely tailored with more fine-grained APIs and API implementations
• Scalability: Resources (memory, number of CPUs, number of machines, …) are allocated to each
API implementation independently, and can therefore be tuned (scaled) to each API
implementation’s specific needs
• Resources: Each API implementation consumes a minimum set of resources (CPUs/vCores,
CloudHub workers, …) and more API implementations - even if they are smaller - typically
means higher resource usage overall
• Complexity: Smaller APIs and API implementations are simpler and therefore more easily
understood and maintained. Compared to larger and hence fewer APIs and API implementations
they also result in more API-related assets visible in the application network and more and more
complex interactions (API invocations). In other words, as the complexity of each node in the
application network is reduced the complexity of the entire application network increases
• Latency: Each additional API invocation adds latency, and smaller APIs therefore cause higher
overall latency - which often must be mitigated through caching, etc. (Module 7)
• Failure modes: Each additional API invocation is an additional remote interaction between
application components, the potential failure of which must be addressed (7.2)
• Team organization: Each API can be implemented independently of all other API
implementations, assuming that the application interfaces between API implementations - in the
form of API specifications - have been agreed. This means that team organization and
parallelization of implementation effort are more flexible with fine-grained APIs and API
implementations: Business Architecture follows Application Architecture [Ref14]
• Agility and innovation: Following from most of the above, smaller APIs and API implementations
typically result in shorter innovation cycles because changes and new features can be deployed
into production more swiftly

© 2020 MuleSoft Inc. 71

Anypoint Platform Architecture Application Networks

4.2.6. Details of the "Aggregator Quote Creation EAPI"

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

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

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 38. "Aggregator Quote Creation EAPI", serving the Aggregator.

4.2.7. Details of the "Policy Holder Search PAPI"

"Policy Holder Search PAPI" 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

© 2020 MuleSoft Inc. 72

Anypoint Platform Architecture Application Networks

"Aggregator Quote Creation EAPI"

• Its API implementation invokes two System APIs, one of them being the "Motor Policy Holder
Search SAPI"

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 39. "Policy Holder Search PAPI", initially serving the API implementation of the "Aggregator
Quote Creation EAPI".

4.2.8. Details of the "Motor Policy Holder Search SAPI"

"Motor Policy Holder Search SAPI" 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 PAPI"
• Its API implementation invokes the Policy Admin System over an unidentified technology
interface (MQ-based, 7.1.3)

© 2020 MuleSoft Inc. 73

Anypoint Platform Architecture Application Networks

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 40. "Motor Policy Holder Search SAPI", exposing existing functionality in the Policy Admin
System, and initially serving the API implementation of the "Policy Holder Search PAPI".

4.2.9. 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.

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 41. How APIs in all tiers serve the "Create Aggregator Quotes" business process.

© 2020 MuleSoft Inc. 74

Anypoint Platform Architecture Application Networks

4.2.10. Exercise 5: 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

© 2020 MuleSoft Inc. 75

Anypoint Platform Architecture Application Networks

Solution

• Only the "Aggregator Quote Creation EAPI" depends on the Aggregator-defined data format
• In the future there will be one Experience API per Aggregator, similar to "Aggregator Quote
Creation EAPI"
• 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:
◦ "Aggregator Quote Creation EAPI": 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 EAPI"
◦ 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 (2.2.11). The current
Aggregator as an existing client of the "Aggregator Quote Creation EAPI" does not experience any
change as the "Aggregator Quote Creation EAPI" 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 EAPI" is paid back immediately by the creation
of the new "One-Step" Process API and the re-use of the orchestration logic hidden in "Aggregator
Quote Creation EAPI".

© 2020 MuleSoft Inc. 76

Anypoint Platform Architecture Application Networks

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 make it a routine to always check first for the possibility of reusing exisiting APIs 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
and publish an Anypoint Exchange entry for each API:

1. A basic API specification, preferably in the form of a RAML definition, is required for each API
2. The creation of the API specification must start in Anypoint Design Center, from where the API
specification can be exported to Anypoint Exchange
3. The version of each API should clearly indicate that it is not production-ready yet, e.g., by using
v0 as the version of the API specification and 0.0.1 for the corresponding first Anypoint
Exchange asset (6.2)
4. A rudimentary API portal for each API is then automatically rendered in Anypoint Exchange

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. The following
examples illustrate the naming conventions used by Acme Insurance for these first steps:

• Anypoint Design Center projects: "Policy Holder Search PAPI", similarly for Experience APIs
(EAPI) and System APIs (SAPI)
• API specification version: v0
• API specification Anypoint Exchange entry: name: "Policy Holder Search PAPI", asset ID:
policy-holder-search-papi (group ID is set by Anypoint Exchange to be the Anypoint
Platform organization ID), version: 0.0.1 (group/asset ID and version form the "Maven
coordinates" of an Anypoint Exchange asset)

4.3.2. Defining RAML

See the corresponding glossary entry.

© 2020 MuleSoft Inc. 77

Anypoint Platform Architecture Application Networks

4.3.3. Defining RAML definition

See the corresponding glossary entry.

4.3.4. Defining OpenAPI Specification (OAS)

See the corresponding glossary entry.

4.3.5. Defining OpenAPI definition

See the corresponding glossary entry.

4.3.6. "Policy Holder Search PAPI" documentation

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

API documentation for the "Policy Holder Search PAPI" is a form of contract for all elements of the
API, i.e., its business service, application service, application interface and technology interface.
The API specification of the API - the RAML definition or OpenAPI definition - 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 API
specification 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 API specification, for instance when
NFRs are addressed
• Other NFRs, like throughput goals are not part of the API specification but the wider API
documentation, specifically the API’s Anypoint Exchange entry

© 2020 MuleSoft Inc. 78

Anypoint Platform Architecture Application Networks

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 42. Documentation for the "Policy Holder Search PAPI", including its API specification in the
form of a 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.7. Using Anypoint Design Center to sketch and simulate an

API specification for "Policy Holder Search PAPI"
Using API designer, a feature of Anypoint Design Center, you sketch a first draft of the API
specification of "Policy Holder Search PAPI" 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 API specification should capture all of these aspects that are currently known about the API,
but may well be at first more of a stub than a complete API specification: it will be amended as the
project progresses and the understanding of the API improves.

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

© 2020 MuleSoft Inc. 79

Anypoint Platform Architecture Application Networks

Figure 43. Using the API designer feature of Anypoint Design Center to sketch and try-out (mock)
"Policy Holder Search PAPI".

4.3.8. Creating engaging and discoverable documentation and

assets for "Policy Holder Search PAPI"
• Anypoint Platform provides two main features for making the documentation for an API
engaging: API Notebooks and API Consoles
• Both, plus optional auxiliary documentation, are part of the Anypoint Exchange entry for an API
• Anypoint Exchange entries for an API are linked to the API specification for that API and provide
the documentation for the API contract
• Anypoint Exchange entries are discoverable within Acme Insurance and may be included in the
organization’s Public (Developer) Portal (Exchange Portal), which makes them discoverable on
the public internet
• Anypoint Exchange entries serve API consumers, i.e. the users of the API, amongst other
audiences (such as operations teams, 10.7.1)

© 2020 MuleSoft Inc. 80

Anypoint Platform Architecture Application Networks

Discoverable API External API

Assets Consumer Consumer

Policy Holder Search Acme Insurance Exchange

API Documentation
Policy Holder Search Acme Insurance Public
API Exchange Entry (Developer) Portal

Policy Holder Search Policy Holder Search Policy Holder

API Notebooks API Console Search auxiliary
Policy Holder Search
RAML Definition documentation

Engaging
Documentation

Figure 44. Publishing an Anypoint Exchange entry for "Policy Holder Search PAPI", including API
Notebooks and an API Console, and optionally including it in Acme Insurance’s Public (Developer)
Portal (Exchange Portal), makes for engaging and discoverable documentation of that API serving
internal and optionally external API consumers.

4.3.9. Publishing an Anypoint Exchange entry for "Policy Holder

Search PAPI"
Anypoint Exchange is a kind of Content-Management System specifically optimized for supporting
application networks. Anypoint Exchange can store many kinds of assets, including API
specifications such as RAML definitions and OpenAPI definitions, connectors, SOAP web services,
and more.

From within the Anypoint Design Center project for "Policy Holder Search PAPI" publish to Anypoint
Exchange, thereby creating an Anypoint Exchange entry of type "REST API" for that API.

The Anypoint Exchange entry for an API is the main entry point to the documentation for that API.
As soon as a first draft of the API specification of "Policy Holder Search PAPI" has been created in
Anypoint Design Center, it should be published to Anypoint Exchange to announce its addition to
the application network. Use versioning to reflect the maturity (or lack thereof) of an API
specification.

Strictly speaking, an Anypoint Exchange entry of type "REST API" is for an API specification. But
Anypoint Exchange provides several features that turn Anypoint Exchange entries for APIs into
comprehensive portals for these APIs:

© 2020 MuleSoft Inc. 81

Anypoint Platform Architecture Application Networks

• It separates consumer- and client-facing version (major version) from asset version (full
semantic version of the API specification artifact): 6.2
• It parses the API specification and renders an API Console called "API summary", which allows
the exploration and mocking of the API
• It keeps track of API instances, i.e., API endpoints on which API implementations accept
requests
• It allows the addition of arbitrary content and specifically supports that creation of API
Notebooks

The manually-added content of an Anypoint Exchange entry for each API should at the very least
document what cannot be expressed in the API specification, such as the HTTPS mutual
authentication requirement for the "Aggregator Quote Creation EAPI".

Every change to the content of that API specification triggers an asset 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 6.2 for a discussion of versioning API-related artifacts.

Figure 45. The Anypoint Exchange entry for "Policy Holder Search PAPI", providing a portal for this
API, including such views as the auto-generated API Console ("API summary") and
instances/endpoints for this and previous versions of this API.

"Policy Holder Search PAPI" can now be discovered in Acme Insurance’s Anypoint Exchange, when
browsing or searching for any kind of asset, including APIs.

© 2020 MuleSoft Inc. 82

Anypoint Platform Architecture Application Networks

You note that when an API specification is published to Anypoint Exchange then a corresponding
Anypoint Connector for Mule applications to invoke the API is also created as a separate Anypoint
Exchange entry (Figure 46).

Figure 46. Publishing an Anypoint Exchange entry based on an API specification auto-generates an
Anypoint Connector to invoke that API from Mule applications.

4.3.10. Understanding the API Console for "Policy Holder

Search PAPI"
Anypoint Platform automatically creates a web UI to browse and trigger API invocations of an API
with an API specification. This feature is available

• when designing an API in Anypoint Design Center

• as part of an API’s Anypoint Exchange entry, where it is called "API summary"
• when implementing the API in Anypoint Studio

The API Console for the "Policy Holder Search PAPI" is automatically included in its Anypoint
Exchange entry, based on the preliminary API specification created earlier. It allows the invocation
of the API against the baseUri from the RAML definition as well as any of its known
instances/endpoints, including the mocking service.

© 2020 MuleSoft Inc. 83

Anypoint Platform Architecture Application Networks

Figure 47. The API Console automatically included in the Anypoint Exchange entry for "Policy
Holder Search PAPI".

4.3.11. Including an API Notebook for "Policy Holder Search

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

Include an API Notebook for the "Policy Holder Search PAPI" in its Anypoint Exchange entry. This
API Notebook makes use of the API’s preliminary API specification created earlier.

The API Notebook can be created as a new, distinct page or API Notebook code cells can be
included in any of the existing (editable) pages. The former is typically preferred, as it makes the
API Notebook stand out. In any case, the essence of an API Notebook are its code cells, which are
demarcated as Markdown fenced code blocks with the notebook info-string
(https://github.github.com/gfm/) and contain JavaScript code.

© 2020 MuleSoft Inc. 84

Anypoint Platform Architecture Application Networks

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

4.3.12. Publishing the Anypoint Exchange entry for "Policy

Holder Search PAPI" to Acme Insurance’s Public (Developer)
Portal (Exchange Portal)
The newly created portal for "Policy Holder Search PAPI" in the form of its Anypoint Exchange entry
can trivially be included in Acme Insurance’s Public (Developer) Portal (Exchange Portal) through
the sharing functionality in Anypoint Exchange (Figure 49).

© 2020 MuleSoft Inc. 85

Anypoint Platform Architecture Application Networks

Figure 49. Sharing the Anypoint Exchange entry for "Policy Holder Search PAPI" allows it to be
published in Acme Insurance’s Public (Developer) Portal (Exchange Portal).

Accessing the Public (Developer) Portal (Exchange Portal) does not require authentication and
authorization and hence only publicly visible APIs should be exposed in this way. (This is clearly not
the case for the "Policy Holder Search PAPI" used here to illustrate the Public (Developer) Portal
(Exchange Portal) - apologies.)

The Public (Developer) Portal (Exchange Portal) can be styled to reflect the Corporate Identify of an
organization.

© 2020 MuleSoft Inc. 86

Anypoint Platform Architecture Application Networks

Figure 50. Acme Insurance’s lightly styled Public (Developer) Portal (Exchange Portal) showing only
publicly visible APIs from Acme Insurance’s application network.

The API instances (endpoints) visible in the Anypoint Exchange entry of an API accessed from the
Public (Developer) Portal (Exchange Portal) are only those that have been marked with public
visibility. By default, this includes the mocking service instance.

© 2020 MuleSoft Inc. 87

Anypoint Platform Architecture Application Networks

Figure 51. The API consumer’s view of the Anypoint Exchange entry for "Policy Holder Search PAPI"
when accessed from Acme Insurance’s Public (Developer) Portal (Exchange Portal).

4.3.13. Repeat for all APIs for the "Create quote for
aggregators" feature
Create rudimentary API specifications and corresponding Anypoint Exchange entries with API
Notebooks and API Consoles for all APIs needed for the "Create quote for aggregators" feature.

© 2020 MuleSoft Inc. 88

Anypoint Platform Architecture Application Networks

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

© 2020 MuleSoft Inc. 89

Anypoint Platform Architecture Application Networks

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 (Figure 35).

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 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 such as API Architects 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, part of 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 as you do
so:

• You discover the existing "Policy Holder Search PAPI" 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
PAPI"

© 2020 MuleSoft Inc. 90

Anypoint Platform Architecture Application Networks

• You define the new "Policy Search PAPI" to support searching for policies across lines of business
(motor and home)
• The "Claims PAPI" currently only needs to support searching for claims across LoBs, but is
envisioned to ultimately grow to support other operations on claims

All-in-all, the following new APIs could serve to realize the functional requirements of the "Retrieve
policy holder summary" feature with an API-led connectivity approach (Figure 53):

• "Mobile Policy Holder Summary EAPI": (policy holder identifier) -> (policy holder status
summary)
◦ Given an identifier of an Acme Insurance policy holder (SSN, customer number, …), returns a
concise, mobile-friendly summary of its status as a customer of Acme Insurance, incl. concise
summary data about policies held, claims open or recently updated, etc.
◦ A particular (strictly speaking non-functional) security aspect this Experience API is that the
policy holder identifier shall not be passed as a normal input parameter but must always be
taken to be the currently authenticated user (OAuth 2.0 resource owner) on whose behalf the
API invocation is made
• "Policy Holder Summary PAPI": (policy holder identifier) -> (policy holder status summary)
◦ Given an identifier of an Acme Insurance policy holder (SSN, customer number, …), returns a
summary of its status as a customer of Acme Insurance, incl. summary data about all policies
held and claims known, etc.
◦ It is assumed that the available policy holder identifier is acceptable input to "Policy Holder
Search PAPI"
◦ The policy holder identifier is passed as a normal input parameter
• "Policy Search PAPI": (policy properties) -> (matching policies)
◦ Based on available data describing a policy (data about policy holder, vehicle, insured home
address, …) returns a description of all matching policies at Acme Insurance, for any LoB
• "Claims PAPI": search: (claim properties) -> (matching claims)
◦ Based on available data describing a claim (data about policy, claimant, vehicle, burgled
home address, …) returns a description of all matching policies at Acme Insurance, for any
LoB
• "Motor Policy Search SAPI": (motor policy properties) -> (matching motor policies)
◦ Searches the Policy Admin System for motor policies matching the given policy data (data
about policy holder, vehicle, …)
• "Home Policy Search SAPI": (home policy properties) -> (matching home policies)
◦ Searches the Policy Admin System for home policies matching the given policy data (insured
home address, …)

© 2020 MuleSoft Inc. 91

Anypoint Platform Architecture Application Networks

• "Motor Claims Search SAPI": (claim properties) -> (matching motor claims)
◦ Searches the Motor Claims System for motor claims matching the given claim properties
(data about policy holder, vehicle, …)
• "Home Claims Search SAPI": (claim properties) -> (matching home claims)
◦ Searches the Home Claims System for home claims matching the given claim properties
(data about policy holder, burgled home address, …)

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 53. 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
You define the "Mobile Auto Claim Submission EAPI" as the interface for the Customer Self-Service
Mobile App and the "Motor Claims Submission SAPI" for the interaction with the Motor Claims
System.

You tentatively define the "Motor Claims Submission PAPI", to insulate the Experience API from the
System API. This is because

• it is 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

All-in-all, the following APIs could serve to realize the functional requirements of the "Submit auto
claim" feature with an API-led connectivity approach (Figure 54):

© 2020 MuleSoft Inc. 92

Anypoint Platform Architecture Application Networks

• "Mobile Auto Claim Submission EAPI": (claim description) -> (acknowledgement)

◦ Accepts the complete description of a claim to be submitted to Acme Insurance and returns
an acknowledgement of the submission.
◦ A particular (strictly speaking non-functional) security aspect of this Experience API is that
the claim being submitted must be against a policy whose policy holder must always be taken
to be the currently authenticated user (OAuth 2.0 resource owner) on whose behalf the API
invocation is made
◦ Processing of the claim submission itself is performed asynchronously and its status can be
retrieved with the submission ID contained in the acknowledgement.
• "Motor Claims Submission PAPI": (claim description) -> (acknowledgement)
◦ Accepts the complete description of a claim to be submitted to Acme Insurance and returns
an acknowledgement of the submission.
◦ The claim submission can be against any policy and policy holder.
◦ Processing of the claim submission itself is performed asynchronously and its status can be
retrieved with the submission ID contained in the acknowledgement.
• "Motor Claims Submission SAPI": (claim description) -> (acknowledgement)
◦ Accepts the complete description of a claim to be submitted to Acme Insurance and returns
an acknowledgement of the submission.
◦ Processing of the claim submission itself is performed asynchronously and its status can be
retrieved with the submission ID contained in the acknowledgement.

© 2020 MuleSoft Inc. 93

Anypoint Platform Architecture Application Networks

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 54. 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 (5.2.3) is not visible in Figure 54.

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 API specifications for the APIs capture the important functional and some non-functional
aspects in a preliminary fashion

© 2020 MuleSoft Inc. 94

Anypoint Platform Architecture Application Networks

• An entry in Acme Insurance’s Anypoint Exchange has been created based on each API’s API
specification, including an API Console and a rudimentary API Notebook for that API, and
pointing to the API’s instances/endpoints (which at this point only comprise those from the
mocking service)
• The Acme Insurance Public (Developer) Portal (Exchange Portal) gives external API consumers
access to all public APIs: these are typically only (some of) the Experience APIs in the
application network
• 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 55. 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 52.

© 2020 MuleSoft Inc. 95

Anypoint Platform Architecture Application Networks

4.5. Building developer communities around APIs with

Anypoint API Community Manager

4.5.1. Introducing Anypoint API Community Manager

Anypoint Exchange shows entries based on API specifications and other types of assets. Because
Anypoint Exchange is tightly integrated into Anypoint Platform, it has access to all information
Anypoint Platform has about an application network, including the API specifications themselves,
their versions, and API instances (4.3.9). Anypoint Exchange entries can be augmented with
manually composed pages (10.7). Anypoint Exchange also allows API consumers to give feedback
on individual entries in the form of reviews and ratings. The same applies to Public (Developer)
Portals (Exchange Portals).

But Anypoint Exchange and Public (Developer) Portals (Exchange Portals) are not general purpose
CMSs (Content-Management Systems), support only limited forms of visual customization, and lack
many interaction channels with API consumers, such as discussion forums. Anypoint API
Community Manager builds on top of the information available in Anypoint Platform and Anypoint
Exchange to provide these and other capabilities [Ref24].

Anypoint API Community Manager allows an organization such as Acme Insurance to build and
operate API consumer communities around their APIs, addressing both internal and external
developers (partners). Anypoint API Community Manager provides customization, branding,
marketing, and engagement capabilities.

APIs cataloged in Anypoint Exchange can be surfaced in Anypoint API Community Manager for API
consumers to discover them and use them to manage API clients, API access credentials, and
consumption metrics.

Anypoint API Community Manager is implemented on Salesforce Community Cloud and accesses
the information it needs about an application network by invoking Anypoint Platform APIs. Being
built on Salesforce Community Cloud, the look and feel, branding, and content of an Anypoint API
Community Manager instance can be extensively customized with Salesforce Community Builder, a
drag-and-drop editor for Salesforce Community Cloud [Ref26]. Similarly leveraging its Salesforce
Community Cloud foundation, Anypoint API Community Manager provides extensive dashboards
and reports about how API consumers interact with assets in Anypoint API Community Manager.

© 2020 MuleSoft Inc. 96

Anypoint Platform Architecture Application Networks

Figure 56. The Anypoint Exchange web UI and Public (Developer) Portals (Exchange Portals) (here
subsumed under "Exchange API portals") on the one hand, and Anypoint API Community Manager
on the other, have access to the same set of API-related assets in Anypoint Platform, which they
retrieve through Anypoint Platform APIs, in particular those for Anypoint Exchange (here called
"Exchange Services").

4.5.2. Taking inspiration from other Anypoint API Community

Manager portals
Acme Insurance currently serves its API consumer community through Anypoint Exchange and the
Acme Insurance Public (Developer) Portal (Exchange Portal), but is exploring the deployment of
Anypoint API Community Manager. In making their decision, Acme Insurance takes inspiration from
existing Anypoint API Community Manager portals by HSBC and KONE Corporation [Ref25].

© 2020 MuleSoft Inc. 97

Anypoint Platform Architecture Application Networks

Figure 57. Anypoint API Community Manager can be extensively branded and customized, including
the Identity Provider used for user management.

© 2020 MuleSoft Inc. 98

Anypoint Platform Architecture Application Networks

Figure 58. Different content sources can be presented in Anypoint API Community Manager. This
includes APIs retrieved from Anypoint Exchange and news articles, but also events, tutorials, blog
posts, and any form of documentation.

© 2020 MuleSoft Inc. 99

Anypoint Platform Architecture Application Networks

Figure 59. API documentation presented in Anypoint API Community Manager can make use of API-
specific components, for example for querying APIs available in Anypoint Exchange, as well as the
full generic feature set of Salesforce Community Cloud.

Figure 60. The API Console familiar from Anypoint Exchange is one of many API-related
components that can be rendered in Anypoint API Community Manager pages.

© 2020 MuleSoft Inc. 100

Anypoint Platform Architecture Application Networks

Figure 61. API consumers can also request access to an API instance through Anypoint API
Community Manager, as well as manage their API clients (applications). API consumers can then
get insights on their API clients' performance as they invoke these APIs.

Figure 62. Administrators of an Anypoint API Community Manager instance use a rich set of tools
and controls to define the APIs to surface in Anypoint API Community Manager, manage CMS-style
content, forums, and all other aspects of that Anypoint API Community Manager instance.

© 2020 MuleSoft Inc. 101

Anypoint Platform Architecture Application Networks

Figure 63. Salesforce Community Builder is the visual drag-and-drop editor used to define the look-
and-feel and structure of Anypoint API Community Manager pages.

© 2020 MuleSoft Inc. 102

Anypoint Platform Architecture Application Networks

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 Anypoint Design Center, API specifications in the form of RAML definitions for each API
were sketched and simulated
• Anypoint Exchange entries with API Console and API Notebook were created and published for
each API
• Acme Insurance plans to expose some APIs from Anypoint Exchange in Anypoint API Community
Manager to provide API consumers with a visually more compelling and more interactive
experience than is possible with Anypoint Exchange and Public (Developer) Portals (Exchange
Portals) alone

© 2020 MuleSoft Inc. 103

Anypoint Platform Architecture Application Networks

Module 5. Enforcing NFRs on the Level of API

Invocations Using Anypoint API Manager

Objectives
• Describe how Anypoint API Manager controls API invocations
• Use API policies to enforce non-functional constraints on API invocations
• Choose between enforcement of API policies in an API implementation, an API proxy, or
Anypoint Service Mesh
• Register an API client for access to an API version
• Describe when and how to pass client ID/secret to an API
• Establish guidelines for API policies suitable for System APIs, Process APIs and Experience APIs
• Describe how Anypoint Security enables de/tokenization and additional Edge policies in Anypoint
Runtime Fabric deployments

© 2020 MuleSoft Inc. 104

Anypoint Platform Architecture Application Networks

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
• 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 64. 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 make a first attempt at selecting a Technology Architecture rooted in
Anypoint Platform features that addresses these NFRs:

• XML/HTTP interface:
◦ Not architecturally significant, should be captured in API specification

© 2020 MuleSoft Inc. 105

Anypoint Platform Architecture Application Networks

• 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 performant runtime plane for API implementations: CloudHub
◦ Need to carefully manage load on Policy Admin System: Anypoint API Manager
• Must not lose quotes
◦ All-synchronous chain of API invocations, hence reliability requirement can be met by a
transactional (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 Anypoint VPC
◦ Should add client authentication on top of HTTPS mutual auth: Anypoint API Manager

© 2020 MuleSoft Inc. 106

Anypoint Platform Architecture Application Networks

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 65. 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 try and address these NFRs:

• Throughput and response time:

◦ Do not seem overly challenging
◦ But future use may change requirements significantly
◦ Select highly scalable runtime plane for API implementations: CloudHub: fits with existing
Technology Architecture

© 2020 MuleSoft Inc. 107

Anypoint Platform Architecture Application Networks

• HTTPS:
◦ Document in API specification
◦ 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, 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

© 2020 MuleSoft Inc. 108

Anypoint Platform Architecture Application Networks

"Retrieve policy holder summary" feature

Submit auto claim

OAuth2 Must not Throughput Async HTTPS

lose claim 10 requ/s fulfillment
submissions

Figure 66. 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
(8.3.1)
◦ Select suitable persistence mechanism to store correlation information for asynchronous
processing:
▪ Mule runtime Object Store as implemented in CloudHub (7.1.14)
• Consistency: to be addressed through event notifications, 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 SAPI". Only after some considerable time has
passed the newly submitted claim becomes visible to the "Motor Claims Search SAPI" 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.

© 2020 MuleSoft Inc. 109

Anypoint Platform Architecture Application Networks

5.3. Using Anypoint API Manager and API policies to

manage API invocations

5.3.1. Reviewing types of APIs

Building on the definition of API, what types of APIs are there?:

• REST APIs
◦ With API specification in the form of a RAML definition or OpenAPI 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, by recruiting the API policy enforcement capability of the Mule runtime on which it
executes
• For external API implementations, i.e., API implementations not implemented as Mule

© 2020 MuleSoft Inc. 110

Anypoint Platform Architecture Application Networks

applications:
◦ A separate, auto-generated Mule application called an API proxy can be deployed in front of
exactly one external API implementation, in a Mule runtime called the API Gateway, to
enforce API policies for the API exposed by that external API implementation
◦ External API implementations deployed to a Kubernetes cluster can use Anypoint Service
Mesh as an add-on to the Kubernetes cluster. Anypoint Service Mesh provisions the Mule
applications and Mule runtimes required for API policy enforcement in a much more efficient,
streamlined, and Kubernetes-native way than would be possible by simply deploying one
generic API proxy for every API implementation in the Kubernetes cluster

The API policies themselves are not included into any of these Mule applications, just the capability
of enforcing API policies via the Mule runtime. This is true for both the API policy template (code)
and API 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

required for download

API Policy Mule runtime

enforcement required for

Embedded Enforcement Enforcement

enforcement through API through
proxy Anypoint
Service Mesh

Figure 67. An API policy consists of a template (code) and definition (data) and its enforcement
requires a Mule runtime, which provides this function. Enforcement can either be performed
embedded in an API implementation itself (if it is a Mule application), or via a separate API proxy
(a dedicated Mule application), or through Anypoint Service Mesh (via a dedicated Mule application
deployed to the same Kubernetes cluster as the API implementations).

5.3.5. Providing API management for Mule applications

An API implementation that is a Mule application by definition executes in a Mule runtime and can
therefore directly make use of the API policy enforcement function of this Mule runtime: it can
embed API policy enforcement.

© 2020 MuleSoft Inc. 111

Anypoint Platform Architecture Application Networks

API Policy
API Policy

download

Mule runtime

API implementation
(Mule app)

HTTP/S
API client
API client
HTTP/S
Mule runtime

API implementation
(Mule app)

download

API Policy
API Policy

Figure 68. The enforcement of API policies for API implementations that are Mule applications can
be performed embedded in the API implementation itself using services provided by the Mule
runtime on which the API implementation executes. Depending on the Anypoint Platform runtime
plane, different API implementations may or must execute in different Mule runtimes.

5.3.6. Providing API management via API proxies

API proxies can enable API policy enforcement (and API analytics) for any API implementation - but
are a must if that API implementation is not a Mule application (so that embedded policy
enforcement is not an option) and is not deployed to a Kubernetes cluster (so that Anypoint Service
Mesh is not an option).

• API proxies are templated Mule applications that can be auto-generated by Anypoint API
Manager
• Being Mule applications, API proxies must be deployed to a Mule runtime, which is then typically
called an API Gateway. The term API Gateway denotes the usage and licensing of these Mule
runtimes, not a technical difference to "normal" Mule runtimes
• In Anypoint Platform runtime planes with iPaaS functionality (such as CloudHub), Anypoint API
Manager can not only auto-generate the API proxy but also deploy it to an auto-provisioned

© 2020 MuleSoft Inc. 112

Anypoint Platform Architecture Application Networks

Mule runtime/API Gateway

• An API proxy provides API management for exactly one API implementation: it cannot perform
API management for more than one API implementation
• API clients must send API invocations to the API proxy instead of directly to the API
implementation
• If the API policies enforced by the API proxy allow an API invocation to proceed, then the API
proxy in turns sends a separate API invocation to the API implementation
• API clients and API implementations can be implemented by any means, as Mule applications or
not: the interface between API client and API proxy, and between API proxy and API
implementation is strictly the HTTP-based API
• API proxies are well-suited for coarsed-grained APIs, where the addition of a separate node - the
API proxy - into the HTTP request-response path between API client and API implementation
does not constitute significant overhead

© 2020 MuleSoft Inc. 113

Anypoint Platform Architecture Application Networks

API Policy
API Policy

download

Mule runtime (API

gateway)

API proxy API

HTTP/S
(templatized Mule implementation
app) (Mule app or not)
HTTP/S
API client
API client
HTTP/S
Mule runtime (API
gateway)

API proxy API

HTTP/S
(templatized Mule implementation
app) (Mule app or not)

download

API Policy
API Policy
(copy)

Figure 69. The enforcement of API policies for API implementations that are not Mule applications
(and are not deployed to a Kubernetes cluster) must be performed in a separate, dedicated,
templated Mule application called API proxy. API proxies recruit the API policy enforcement feature
of the Mule runtime on which they execute, which is called API Gateway. Typically, every API proxy
is deployed to its own dedicated Mule runtime, thereby introducing at least one separate node for
each API implementation. API clients must invoke the API proxy explicitly.

5.3.7. Providing API management for external API

implementations deployed to a Kubernetes cluster
Anypoint Service Mesh enables API policy enforcement (and API analytics) via the Anypoint
Platform control plane for external API implementations deployed to a Kubernetes cluster.

• Because Kubernetes-native API implementations are typically fine-grained, the addition of one
separate API proxy for every such API implementation would introduce unacceptable overhead
• Anypoint Service Mesh can be installed by customers into their customer-hosted Kubernetes
clusters, supported on:
◦ Google Kubernetes Engine (GKE)
◦ Amazon Elastic Kubernetes Service (EKS)

© 2020 MuleSoft Inc. 114

Anypoint Platform Architecture Application Networks

◦ Azure Kubernetes Service (AKS)

• An Anypoint Service Mesh installation builds on Istio (which uses Envoy), which is therefore
required in the Kubernetes cluster before Anypoint Service Mesh can be installed
• Anypoint Service Mesh provides and fully manages the Mule application and (cluster of) Mule
runtimes required for API policy enforcement as replicated pods in a Kubernetes namespace.
This Mule application and Mule runtime are the equivalent of API proxy and API Gateway in API
proxy-based policy enforcement (5.3.6)
• API management for all API implementations in a given Kubernetes namespace is performed
through the same set of Mule runtime pods, eliminating the to-1 relationship restriction of API
proxies
• API clients continue sending API invocations to the Kubernetes service representing a given API
implementation: Istio/Envoy transparently intercepts all API invocations to/from an API
implementation and routes them to the Mule runtime/Mule application performing API policy
enforcement. This is transparent to API clients - if it were not for the effect of the NFRs enforced
by the applied API policies

Current Anypoint Service Mesh restrictions are:

• Cannot enforce automated policies and custom API policies

• Cannot link to customer-hosted Anypoint Platform control planes
• Only supports a limited set of the API policies otherwise available in Anypoint API Manager (and
described below)

© 2020 MuleSoft Inc. 115

Anypoint Platform Architecture Application Networks

API Policy API Policy

API Policy API Policy

Kubernetes cluster download download

Kubernetes namespace

Mule runtime (pods)

Mule app
(productized, part of
Anypoint Service
Mesh

via Istio/Envoy

Kubernetes- API via Istio/Envoy

HTTP/S
deployed API implementation
client (service, pods)

Non-Kubernetes HTTP/S API

API client implementation
(service, pods)

Figure 70. The enforcement of API policies for API implementations that are not Mule applications
and are deployed to a Kubernetes cluster (as Kubernetes services and pods) is best performed via
Anypoint Service Mesh. Part of Anypoint Service Mesh is a dedicated Mule application and Mule
runtimes that are deployed as separate pods in the same Kubernetes namespace as the API
implementations. Through Istio/Envoy, employed by Anypoint Service Mesh, API policy
enforcement is performed via this Mule application for all API implementations in that namespace,
without the API clients having to change the endpoint addresses at which they invoke their APIs.
One set of Anypoint Service Mesh-provided Mule runtime/Mule application pods suffices to perform
API policy enforcement (and API management/analytics in general) for all - typically fine-grained -
API implementations in a Kubernetes cluster namespace.

© 2020 MuleSoft Inc. 116

Anypoint Platform Architecture Application Networks

5.3.8. Exercise 6: Pros and cons of different approches to API

policy enforcement
Compare the characteristics of the sites of API policies enforcement available in Anypoint Platform:

• List scenarios/requirements that would be best addressed by API policy enforcement embedded
in the API implementation, in an API proxy, or through Anypoint Service Mesh, respectively

© 2020 MuleSoft Inc. 117

Anypoint Platform Architecture Application Networks

Solution

The following scenarios call for API proxies, Anypoint Service Mesh, or embedded API policy
enforcement:

API implementations are not Mule applications but external API implementations:

• API implementations are not Mule applications and hence do not execute in Mule runtimes:
Embedded API policy enforcement is not possible, only API proxies or Anypoint Service Mesh,
and the latter only if the API implementations are deployed to a Kubernetes cluster
• API implementations are deployed to a Kubernetes cluster as non-Mule applications: Anypoint
Service Mesh is the most idiomatic and efficient API policy enforcement approach

API implementations are Mule applications:

• Resource-usage must be minimized: embedded API policy enforcement is preferred because

number of nodes approximately doubles when API proxies are used
• Deployment architecture and CI/CD must be as simple as possible: embedded API policy
enforcement is preferred
• API policies with special resource requirements are applied: API proxies preferred because they
allow these API policies to be deployed to dedicated machines (both in number and size)
◦ E.g., a caching API policy is best served by a few machines with large amounts of RAM, and
API proxies can be configured accordingly
◦ E.g., a security API policy may require access to a local Hardware Security Module (HSM),
and API proxies can be deployed to machines that have this available
• API policies require special network configuration, such as access to a highly secure service that
is only accessible from a particular subnet: API proxies are preferred because they can be
deployed to a different network than the API implementations
• Security sensitive APIs, such as sensitive externally accessible Experience APIs: API proxies
preferred because they can be deployed to a DMZ and they can also shield API implementations
from DoS or similar attacks, which would be rejected by the API proxy 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

© 2020 MuleSoft Inc. 118

Anypoint Platform Architecture Application Networks

5.3.9. Managing APIs with Anypoint API Manager

Anypoint API Manager is an Anypoint Platform component which provides the following capabilities:

• Management of APIs using the concept of API instances

◦ An API instance is an entry in Anypoint API Manager that represents a concrete API endpoint
for a specific major version of an API in a specific environment (Staging, Production, …)
• Configuration of API policies for a given API instance
◦ by selecting an API policy template and parameterizing it with an API policy definition
• Configuration of automated policies for all API instances in a given environment
• Configuration of API Groups that bundle API instances and streamline some API management
tasks common to the group
• Configuration of custom API policies in addition to the ones provided by Anypoint API Manager
out-of-the-box (5.3.12)
• Is contacted from the site of API policy enforcement to download all API policies that must be
enforced
• Definition of alerts based on the characteristics of API invocations
• Admin of API clients ("Client Applications" or "Contracts") that have requested access to APIs
◦ API consumers use Anypoint Exchange to request access to an API
• Gives access to Anypoint Analytics

© 2020 MuleSoft Inc. 119

Anypoint Platform Architecture Application Networks

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

An automated policy is defined in a specific environment in Anypoint API Manager and for a specific
version of the Mule runtime. The automated policy is then automatically applied to all current and
future API instances in that envrionment for which API policy enforcement is performed in a
matching Mule runtime.

An API instance must also declare the asset version (full semantic version) currently being exposed
by this endpoint. The asset version (e.g., 2.3.4) must be compatible with the major API version
(e.g., v2) and can be updated during the lifetime of the API instance.

Multiple API instances can be bundled into an API Group instance. An API Group exists in a specific
organization and environment. Adminstrators can apply SLA tiers to the entire group of API
instances (5.3.25). API clients can request access to an API Group instance to gain access all API
instances in that group, rather than having to individually request access to each API instance
(5.3.26). API policies cannot be applied to API Group instances.

5.3.10. Selectively applying an API policy to some resources

and methods of an API
APIs defined with an API specification - be it a RAML definition or an OpenAPI definition - can apply
API policies not just to the entire API endpoint (represented in Anypoint API Manager as an API
instance) but to selected combinations of API resources and HTTP methods. This configuration is

© 2020 MuleSoft Inc. 120

Anypoint Platform Architecture Application Networks

performed when configuring the API policy and is then applied at the time when the API policy is
enforced.

5.3.11. API policies available on Anypoint Platform

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

• Compliance
◦ Client ID enforcement
◦ Cross-Origin Resource Sharing (CORS) (control thereof)
• Security
◦ HTTP Basic Authentication API policies
▪ Basic Authentication - LDAP
▪ Basic Authentication - Simple
◦ IP-based API policies
▪ IP blocklist (= the name used here for what is officially still called "IP blacklist")
▪ IP allowlist (= the name used here for what is officially still called "IP whitelist")
◦ Threat protection API policies
▪ JSON threat protection
▪ XML threat protection
◦ OAuth 2.0 access token enforcement API policies
▪ OAuth 2.0 access token enforcement using Mule OAuth provider
▪ OpenAM access token enforcement
▪ PingFederate access token enforcement
▪ OpenId Connect access token enforcement
◦ JWT Validation
◦ Tokenization-related API policies only available with Anypoint Security in Anypoint Runtime
Fabric (5.4.3)
• QoS
◦ SLA-based API policies
▪ Rate Limiting - SLA-based
◦ non-SLA-based API policies
▪ Rate Limiting
▪ Spike Control

© 2020 MuleSoft Inc. 121

Anypoint Platform Architecture Application Networks

▪ HTTP Caching
• Transformation
◦ HTTP header manipulation API policies
▪ Header Injection
▪ Header Removal
• Troubleshooting
◦ Message Logging

The following API policies were available previously when being enforced on Mule 3 runtimes and/or
older versions of Anypoint Platform:

• Replaced by or included in newer versions of HTTP Basic Authentication API policy:

◦ HTTP Basic Authentication
◦ LDAP security manager (injection thereof)
◦ Simple security manager (injection thereof)
• Replaced by Spike Control API policy:
◦ Throttling
◦ Throttling - SLA-based
• Replaced by Header Injection/Removal API policies:
◦ Add/remove request/response headers

Figure 72. 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.

© 2020 MuleSoft Inc. 122

Anypoint Platform Architecture Application Networks

5.3.12. Understanding custom API policies

API policies can be seen as a form of Aspect-Oriented Programming (AOP) applied to API
invocations:

• API policies are ordered in a chain, with the API implementation or API proxy as the last element
• An incoming HTTP request for an HTTP endpoint exposed by the API is passed down this chain,
and the outgoing (returning) HTTP response is passed up the chain
• API policies implement what is called an "around advice" in AOP, i.e., they execute code before
handing control to the next element in the chain and after the next element in the chain has
handed-back control, altering the HTTP request or response if desired
• In Mule 4 runtimes, API policies can also be applied to outgoing HTTP requests, i.e., these API
policies can define a separate "around advice" that applies to HTTP requests sent by the API
implementation or API proxy and incoming (returning) HTTP responses subsequently received

The mechanics of implementing and applying custom API policies is as follows:

• Custom API policies must be implemented very similar to Mule applications

• They must be packaged specifically as API policies and deployed to Anypoint Exchange
• This package contains the API policy template, i.e., both the code for the API policy as well as a
YAML file that describes the API policy’s configuration data, i.e., the parameters to be specified
when the policy is applied to an API
• When applying an API policy to an API instance, Anypoint API Manager retrieves the API policy
template from Anypoint Exchange and renders a configuration UI to enter the definition
(parameter values)
• The API policy template and definition are then downloaded as usual to any Mule runtime that
registers as that API instance

5.3.13. 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 5.3.27.

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

© 2020 MuleSoft Inc. 123

Anypoint Platform Architecture Application Networks

• 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.

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

discussion of CORS.

5.3.14. Introducing security-related API policies

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

• Authentication/Authorization
• IP-based access control
• Payload threat protection
• Tokenization (5.4.3)

5.3.15. 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
• OpenId Connect access token enforcement requires an Identity Provider compatible with OIDC
(incl. Dynamic Client Registration), such as Salesforce Identity, Okta, and OpenAM
• OAuth 2.0 access token enforcement using Mule OAuth 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 must be used
as the OAuth 2.0 provider for this API policy [Ref30]
◦ Use of this API policy is discouraged other than for testing and exploration

© 2020 MuleSoft Inc. 124

Anypoint Platform Architecture Application Networks

5.3.16. Understanding the interaction between Anypoint

Platform, Identity Provider, and the access token enforcement
policy
The core responsibility of an Identity Provider for Client Management is to validate OAuth 2.0
access tokens presented by API clients in API invocations to an API that is protected by the
matching access token enforcement API policy - such as PingFederate access token enforcement.

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 receive client ID
and secret values that are in sync between Anypoint Platform and the Identity Provider.

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 73. 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.

The client ID assigned to an API client is immutable, but other properties of the API client
application, such as the client secret, the application URL, or the OAuth 2.0 redirect URL, could
require changing over the lifetime of an API client application. Changing ("rotating") the client
secret for a given client ID is particularly relevant for security reasons, so this will be used as the
prototypical use case for the following discussion.

© 2020 MuleSoft Inc. 125

Anypoint Platform Architecture Application Networks

Both Anypoint Platform and commonly used Identity Providers support client secret rotation - but
care must be taken that such a change is propagated to the other party, lest the client secret in
Anypoint Platform and the Identity Provider will be out-of-sync after such a change. This is
inevitable for OIDC DCR because it does not specify a mechanism for updating client secrets - but
Anypoint Platform implements an extension to OIDC DCR to enable updates from Anypoint Platform
to the Identity Provider (see below). Specifically:

• Anypoint Platform triggers the creation of an API client application in the Identity Provider, and
at this point client ID and secret are stored and in-sync in Anypoint Platform and the Identity
Provider. Any changes to the client secret from that point onwards are by default not synced in
either direction
• The client secret can be rotated in the Identity Provider, but the changed secret is not synced
back to Anypoint Platform. If the secret is changed in the Identity Provider then it becomes out-
of-sync with the secret stored in Anypoint Platform and therefore:
◦ For OAuth 2.0: API clients must use the new client secret when obtaining an OAuth 2.0
access token from the Identity Provider. This token can be validated successfully through the
matching OAuth 2.0 token enforcement API policy in Anypoint Platform, because that policy
delegates OAuth 2.0 access token validation to the Identity Provider
◦ For non-OAuth 2.0 API policies like Client ID enforcement: API clients must send the old
client secret with the API invocation, because client ID and secret in the API invocation are
validated against client ID and secret stored in Anypoint Platform
• If a strictly OIDC DCR-compatible Identity Provider is configured for Client Management in
Anypoint Platform, then Anypoint Platform does not allow rotating the client secret, because the
changed secret cannot be synced to such an Identity Provider, and hence the secret changed in
Anypoint Platform would become out-of-sync with the secret stored in the Identity Provider
◦ However, Anypoint Platform implements an extension to OIDC DCR that allows Anypoint
Platform to send a HTTP PUT/DELETE request to an external application when an API client
application is changed/deleted in Anypoint Platform. If this extension is enabled, then a client
secret change results in an HTTP PUT from Anypoint Platform to that application. That
application cannot be the Identity Provider itself, though, because these HTTP requests are
not standardized by OIDC DCR. Instead, the application must be an adapter that hides the
Identity Provider and translates all OIDC DCR invocations plus these proprietary PUT/DELETE
requests into invocations of the Identity Provider

5.3.17. Introducing API policies for HTTP Basic Authentication

In addition to the above OAuth 2.0-based API policies, Anypoint Platform also supports API policies
that enforce HTTP Basic Authentication.

The "HTTP Basic Authentication" API policy must be backed by one of these Security Managers:

© 2020 MuleSoft Inc. 126

Anypoint Platform Architecture Application Networks

• 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.

Alternatively, if the API implementation is deployed to a Mule 4 runtime, the

• Basic Authentication: LDAP

• Basic Authentication: Simple

API policies configure the functionality of a Simple or LDAP security manager inside the API policy
itself and therefore do not require a separate "Security Manager Injector" API policy.

5.3.18. Understanding JSON Web Tokens (JWTs)

Quoting the spec [Ref20] (formatting changed):

• JSON Web Token (JWT) is a compact claims representation format intended for space
constrained environments such as
◦ HTTP Authorization headers and
◦ URI query parameters.
• JWTs encode claims to be transmitted as a JSON object that is used
◦ as the payload of a JSON Web Signature (JWS) structure or
◦ as the plaintext of a JSON Web Encryption (JWE) structure,
• enabling the claims to be
◦ digitally signed or integrity protected and/or
◦ encrypted.
• JWT Claims Set: A JSON object that contains the claims conveyed by the JWT.
• Claim: A piece of information asserted about a subject. A claim is represented as a name/value
pair:
◦ A Claim Name is always a string.
◦ A Claim Value can be any JSON value.
• The contents of the JOSE Header describe the cryptographic operations applied to the JWT
Claims Set.
• Unsecured JWTs: created without a signature or encryption.

Example quoted from the spec [Ref20]:

© 2020 MuleSoft Inc. 127

Anypoint Platform Architecture Application Networks

• JWS JWT example:

◦ JOSE Header declares that the encoded object is a JWT, and the JWT is a JWS that is MACed
using the HMAC SHA-256 algorithm:

1 {
2 "typ": "JWT",
3 "alg": "HS256"
4 }

◦ JWT Claims Set:

1 {
2 "iss": "joe",
3 "exp": 1300819380,
4 "http://example.com/is_root": true
5 }

◦ Both JSON objects are then normalized, base64-encoded, MACed, the MAC is normalized and
base64-encoded, and all 3 parts are concatenated with . to form the complete JWT:

1 eyJ0<snip>NiJ9.eyJp<snip>VlfQ.dBjf<snip>EjXk

• Unsecured JWT:
◦ JOSE Header:

1 { "alg": "none" }

◦ JWT Claims Set as above

◦ Complete JWT:

1 eyJh<snip>lIn0.eyJp<snip>VlfQ.

5.3.19. Understanding JWT Claims

Quoting the spec [Ref20] (formatting changed):

• Registered Claim Names are registered in the IANA "JSON Web Token Claims" registry:

© 2020 MuleSoft Inc. 128

Anypoint Platform Architecture Application Networks

◦ "iss" (Issuer) Claim

◦ "sub" (Subject) Claim
◦ "aud" (Audience) Claim
◦ "exp" (Expiration Time) Claim
◦ "nbf" (Not Before) Claim
◦ "iat" (Issued At) Claim
◦ "jti" (JWT ID) Claim
• Public Claim Names:
◦ either be registered in the IANA "JSON Web Token Claims" registry
◦ or be a Collision-Resistant Name.
• Private Claim Names:
◦ agreed between producer and consumer of a JWT

5.3.20. Propoagating user claims in JWTs within an application

network
• JWTs can be used to reliably transmit with an application network claims about a user on whose
behalf an API invocation is performed, from Experience APIs via Process APIs and System APIs
down to backend systems.
◦ The subject of the JWT is thereby the user, and the Claims Set in the JWT are statements
about that user.
• This is logically distinct from authenticating that user towards external API clients that invoke
Experience APIs, often via OAuth 2.0. This is although OAuth 2.0 access tokens typically use
JWT format.
• An application network-internal Claims Set can include more and proprietary information about a
user. This might include legacy identities of the user required for accessing backend systems.

© 2020 MuleSoft Inc. 129

Anypoint Platform Architecture Application Networks

Figure 74. The interaction of external API clients with Experience APIs and the API invocations
within an application network form two logically distinct realms of token usage. Experience APIs sit
at the boundary between those two realms. OAuth 2.0 access tokens created by an Identity
Provider acting as an OAuth 2.0 server are typically used in the former realm, whereas JWTs can
be used in the latter realm to transmit an application network-internal Claims Set about the current
user. (JWTs are thereby used as User Claims tokens.)

5.3.21. Understanding JWT signing and signature validation

JWT signing (signature creation) and signature validation must both follow JWS [Ref21]

• JWT/JWS terminology expresses this as "the JWT is a JWS"

• A signature is based either on a Message Authentication Code (MAC) or a digital signature:
◦ MACs use the HMAC algorithm (for example, HMAC SHA-256) and require a shared secret to
be available both for signing and signature validation [Ref22]
◦ Digital signatures use the RSA (for example, RSASSA-PKCS1-v1_5 using SHA-512) or ECDSA
algorithms (for example, ECDSA using P-521 and SHA-512) and require a public/private key
pair, where signing requires the private key and signature validation requires the public key
(certificate) [Ref22]
◦ Both enable integrity checking the JWT Claims Set, confirming that it has not been tampered
with after creation
◦ Only digital signatures enable origination identification, confirming that the creator of the JWT
is indeed who they say they are because they are by definition in posession of the private key
used for signing the JWT

© 2020 MuleSoft Inc. 130

Anypoint Platform Architecture Application Networks

• Signatures don’t hide the JWT Claims Set from third parties, because they are not a form of
encryption (which JWE would provide)

Signature validation by the JWT recipient requires access to the shared secret (for HMAC) or public
key (for a digital signature) that matches the shared secret or private key, respectively, used for
signing the JWT. The shared secret or public key are typically retrieved by the JWT recipient from a
JWKS server at a URL known to the JWT recipient [Ref23].

5.3.22. Introducing the JWT validation API policy

This policy validates a JWT in an incoming HTTP request and then validates and propagates the
token’s Claims Set. By default, the JWT is extracted from the HTTP Authorization header as a
Bearer token.

Signature validation:

• Rejects an incoming HTTP request if its JWT does not pass signature validation
• Does not support JWE (encrypted) JWTs
• Supports JWS (signed) JWTs, validating the token’s signature
◦ Confined to a subset of JWS-supported algorithms (HMAC and RSA)
◦ Shared secret or public key can be specified in the policy definition or retrieved from a JWKS
server
• Supports unsecured (unsigned, unencrypted) JWTs
• Can also simply ignore a token’s signature even if present

Claims Set validation:

• Rejects an incoming HTTP request if the Claims Set in the JWT does not match configured
constraints
• Supports all types of JWT Claims (registered, public, private)

Claims Set propagation:

• Propagates the Claims Set to the Mule application to which the JWT validation API policy is
applied
• This is a local, in-process propagation in an in-memory variable

© 2020 MuleSoft Inc. 131

Anypoint Platform Architecture Application Networks

5.3.23. 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

• nesting levels
• string length
• number of elements

etc.

5.3.24. Introducing QoS-related API policies

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

• Rate Limiting (SLA-based and not)

• Spike Control
• HTTP Caching

The first two of these API 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
• Spike Control queues requests beyond the throughput limit and delays and limits reprocessing of
these requests

Anypoint Platform provides two different ways to define the throughput limit enforced by the Rate
Limiting API policy:

• Non-SLA-based, where a throughput limit is defined on the API policy definition associated with
a particular API instance
◦ Limit is enforced for that API instance 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 instance at a particular SLA tier
◦ Limit is enforced separately for each registered API client

Spike Control is only available non-SLA-based.

© 2020 MuleSoft Inc. 132

Anypoint Platform Architecture Application Networks

An SLA-based API policy requires the API client to identify itself with a client ID: 5.3.27. 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 may contain 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
• 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

Returning these HTTP response headers is optional (configurable) and should only be done if API
clients are internal to the organization, such that external API clients do not become privy to how
QoS is enforced for the API.

5.3.25. 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 instance has SLA tiers defined then every API client that registers for access to that API
instance is assigned to exactly one SLA tier and is thereby promised the QoS offered by that SLA
tier.

An SLA tier for an API instance 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 instance
• requires either manual approval or supports automatic approval of API clients requesting usage
of that SLA tier
◦ typically, SLA tiers that confer high QoS guarantees require manual approval

To enforce the throughput limits of an SLA tier, an SLA-based Rate Limiting API policy needs to be
configured for that API instance. 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

© 2020 MuleSoft Inc. 133

Anypoint Platform Architecture Application Networks

client ID/client secret pair sent in the API invocation to the API.

SLA tiers can also be assigned to an API Group instance and thereby to all API instances in that
group. The throughput limits of an SLA tier applied to a group can be refined for individual API
instances in that group. The enforcement of the throughput limits, as always, must occur through
the appropriate SLA-based API policies applied to the API instances - API policies cannot be applied
to the API Group instance.

5.3.26. Registering API clients with an Anypoint Platform-

managed API
API clients that wish to invoke an API that has client ID-based API policy defined, must be
registered for access to the API instance. Access must be requested by the API consumer for that
particular API client through the Anypoint Exchange entry for that API instance, accessed either
directly from Anypoint Exchange or via the Public (Developer) Portal (Exchange Portal). In either
case, requesting access to an API requires an Anypoint Platform user account.

In Anypoint Platform, an API client requesting access or having been granted access to an API is
called "application". The resulting relationship between API and API client is called a "contract" in
Anypoint API Manager.

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 instance.

Figure 75. An API consumer is using the Anypoint Exchange entry for a particular (major) version
of "Aggregator Quote Creation EAPI" to request access to an API instance of that API for an API
client (application) called Aggregator.

© 2020 MuleSoft Inc. 134

Anypoint Platform Architecture Application Networks

Figure 76. Anypoint API Manager web UI showing the Aggregator as the only API client (application
"contract") registered for access to this particular API instance of "Aggregator Quote Creation
EAPI". The Aggregator is registered with the "Standard" SLA tier.

API Group instances bundle several API instances for the main benefit of enabling API consumers to
request access for a particular API client to the group and thereby gain access to each API instance
in that group. This establishes a group-level contract in Anypoint API Manager (and a potential
Identity Provider configured for Client Management), similar to the API-level contract described
previously. (It follows that all API instances in an API Group instance must use the same Identity
Provider for Client Management.) Just as for API instances, requesting access to an API Group
instance is peformed through Anypoint Exchange. To enable this, API Groups can be published to
Anypoint Exchange from Anypoint API Manager, so that API Groups and API Group instances
receive their own Anypoint Exchange entries, distinct from those of the individual APIs and API
instances.

When requesting access to an API instance or API Group instance with one or more SLA tiers, one
SLA tier must be selected by the API consumer when requesting access (Figure 75).

5.3.27. 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. Available
options are:

© 2020 MuleSoft Inc. 135

Anypoint Platform Architecture Application Networks

• 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 currently 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

SLA-based Rate Limiting requires the SLA tier of the API client making the current API invocation to
be retrieved by the client ID supplied in the API invocation. This API policy therefore implicitly also
enforces the presence and validity of the client ID, and, as a convenience, optionally, also the client
secret. It therefore can subsume the functionality of the Client ID enforcement API policy.

OAuth 2.0 access tokens implicitly carry the identity of the API client and its client ID, because:

• The API client (and its client ID/secret) is known to both Anypoint Platform and the OAuth 2.0
server (the Identity Provider registered for Client Management with Anypoint Platform)
• When the API client retrieves a token from the OAuth 2.0 server, it does so by identifying itself
with its client ID
• The OAuth 2.0 access token enforcement API policy exchanges the token for the client ID and
passes it to any downstream SLA-based API policy

Therefore, client secret validation is often turned off if the SLA-based API policy is combined with
an OAuth 2.0 access token enforcement API policy. In this case, the OAuth 2.0 API policy
exchanges the token for the client ID and makes the client ID available to the SLA-based API
policy.

5.3.28. Introducing the HTTP Caching API policy

HTTP Caching is a QoS-based API policy that performs server-side caching, i.e., the cache is
maintained at the site of API policy enforcement (in the API implementation proper or an API proxy
in front of that API implementation) rather than at/by the API client.

The API policy caches entire HTTP responses, incl. the HTTP response status code, HTTP response
headers and the HTTP response body. There is a size limit for cached HTTP responses (currently

© 2020 MuleSoft Inc. 136

Anypoint Platform Architecture Application Networks

1MB).

Caching is only performed for HTTP requests for which a configurable expression evaluates to true.
By default, this expression tests that the HTTP method is GET or HEAD, i.e., is safe (6.4.6).

Similarly, caching is only performed for HTTP responses for which a configurable expression
evaluates to true. By default, this expression tests that the status code is in a restricted set of 2xx,
3xx, 4xx or 5xx codes.

By default the HTTP Caching API policy honors many of the caching directives (HTTP headers)
defined by the HTTP standard (6.4.7).

Cache invalidation of one or all cache entries can be performed by sending a HTTP request with a
configurable HTTP request header and the value invalidate or invalidate-all, respectively.

Various parameters of the HTTP Caching API policy determine how exactly caching is performed:

• Cache entries are stored by a string key defined via a DataWeave expression. By default, this is
the request path, excl. query parameters
• The size of the cache in terms of number of entries must be limited
• Cache entries expire as determined by a configurable time-to-live
• The cache can be distributed such that the same cache entries are seen by all replicas of the API
policy (corresponding to replicas of the API implementation or API proxy to which the API policy
is applied). This results in the cache being maintained in a CloudHub Object Store as described
in 7.1.15
• The cache can also be persistent such that it survives restarts of the API implementation, which
again means that it must be maintained in a CloudHub Object Store

5.3.29. Introducing transformation API policies

Anypoint Platform provides API policies to manipulate HTTP headers in HTTP requests and HTTP
responses:

• Header Injection
• Header Removal

The values for the injected headers are DataWeave expressions, and hence can be dynamically
evaluated.

They are useful, for instance, as one part of a solution for propagating transaction IDs as HTTP
headers along chains of API invocations.

© 2020 MuleSoft Inc. 137

Anypoint Platform Architecture Application Networks

5.3.30. Exercise 7: 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. Also define the order for these API policies
5. Are there any API policies missing that you would want to apply?

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 77. All APIs collaborating for the "Aggregator Integration" product.

See Figure 72.

© 2020 MuleSoft Inc. 138

Anypoint Platform Architecture Application Networks

Solution

See 5.3.31, 5.3.32, 5.3.33 and 5.3.34.

© 2020 MuleSoft Inc. 139

Anypoint Platform Architecture Application Networks

5.3.31. Choosing appropriate API policies for System APIs

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

• IP allowlisting to the IP address range of the API implementations of Process APIs (assuming
they execute in a subnet that assigns well-defined source IPs to them)
• Must always define SLA tiers that require manual approval
• SLA-based Rate Limiting API policy must enforce the QoS of the chosen SLA tier
• Spike Control API policy must protect the backend system from temporary API invocation bursts
by evening them out and enforces the published overall throughput guarantee
◦ X-RateLimit- HTTP response headers should not be exposed to API clients from this API
policy but from the SLA-based API policy
• These API policies should be applied in this order and thereby enforce strict compliance for this
critical class of APIs

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

Figure 78. API policies defined for a particular API instance of the "Policy Options Retrieval SAPI".
Note the automatic application of all automated policies defined in this environment that match the
version of the Mule runtime that performs API policy enforcement for this API instance.

© 2020 MuleSoft Inc. 140

Anypoint Platform Architecture Application Networks

5.3.32. Choosing appropriate API policies for Process APIs

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

• IP allowlisting to the IP address range of the API implementations of Process APIs and
Experience APIs (assuming they execute in a subnet that assigns well-defined source IPs to
them)
• May define non-SLA-based API policies but should then use Client ID enforcement, such that the
identity of API clients is always known and available for API-based analytics (Module 10)
• If SLA tiers are defined then SLA-based Rate Limiting API policy must enforce the QoS of the
chosen SLA tier
• Spike Control API policy must protect from temporary API invocation bursts by evening them out
and enforces the published overall throughput guarantee
◦ X-RateLimit- HTTP response headers should not be exposed to API clients from this API
policy
• These API policies should be applied in this order

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

Figure 79. API policies defined for a particular API instance of the "Policy Holder Search PAPI". Note
the automatic application of all automated policies defined in this environment that match the
version of the Mule runtime that performs API policy enforcement for this API instance.

© 2020 MuleSoft Inc. 141

Anypoint Platform Architecture Application Networks

5.3.33. 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 EAPI" consumed by the Aggregator you define the following:

• IP allowlisting to the IP address of the Aggregator, to complement TLS mutual authentication

• XML threat protection
• One SLA tier for the required 1000 requs/s, which makes this SLA explicit and allows monitoring
and reporting on the SLA
• SLA-based Rate Limiting (not Spike Control)
◦ X-RateLimit- HTTP response headers should not be exposed to API clients from this API
policy because API clients are external
• No Spike Control API policy, to limit the resource consumption incurred by queuing requests
• These API policies should be applied in this order

Figure 80. API policies defined for a particular API instance of the "Aggregator Quote Creation
EAPI". Note the automatic application of all automated policies defined in this environment that
match the version of the Mule runtime that performs API policy enforcement for this API instance.

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

© 2020 MuleSoft Inc. 142

Anypoint Platform Architecture Application Networks

• JSON threat protection

• OAuth 2.0 access token enforcement matching the Identity Provider configured for Client
Management
• Non-SLA-based Rate Limiting (not Spike Control) to 100 requs/s for "Mobile Policy Holder
Summary EAPI" and 10 requs/s for "Mobile Auto Claim Submission EAPI"
◦ X-RateLimit- HTTP response headers should not be exposed to API clients from this API
policy because API clients are external
• No Spike Control API policy, to limit the resource consumption incurred by queuing requests
• These API policies should be applied in this order

Figure 81. API policies defined for a particular API instance of the "Mobile Policy Holder Summary
EAPI". The "OAuth 2.0 access token enforcement using external (Mule OAuth) provider" API policy
should be replaced with one that fits the Identity Provider configured for Client Management. Note
that there is currently no Mule runtime deployed that performs API policy enforcement for this API
instance (see the "unregistered" status). Anypoint API Manager can therefore not determine which,
if any, of the automated policies defined in this environment can be applied to this API instance.

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

• Allowlisting of IP address range of API clients, if possible

• Protection against oversized JSON/XML payloads
• Some form of enforcement of API client identity and, if applicable, user identity (via OAuth 2.0)
• Rate Limiting instead of Spike Control to reduce resource consumption in case of excessive
number of API invocations, such as during DoS attacks. No exposure of X-RateLimit- HTTP
response headers

© 2020 MuleSoft Inc. 143

Anypoint Platform Architecture Application Networks

• No Spike Control API policy

• These API policies should be applied in this order

5.3.34. Reviewing API policies for the APIs involved in the

"Create quote for aggregators" feature

Figure 82. API policies applied to APIs in all tiers collaborating for the "Create quote for
aggregators" feature (the suggested order of API policies is not visible in this diagram).

5.3.35. Reviewing API policies for the APIs involved in the

"Retrieve policy holder summary" feature

© 2020 MuleSoft Inc. 144

Anypoint Platform Architecture Application Networks

Figure 83. API policies applied to APIs in all tiers collaborating for the "Retrieve policy holder
summary" feature (the suggested order of API policies is not visible in this diagram).

5.3.36. Reviewing API policies for the APIs involved in the

"Submit auto claim" feature

© 2020 MuleSoft Inc. 145

Anypoint Platform Architecture Application Networks

Figure 84. API policies applied to APIs in all tiers collaborating for the "Submit auto claim" feature
(the suggested order of API policies is not visible in this diagram).

5.3.37. Reflecting the application of API policies in the API

specification 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 the

© 2020 MuleSoft Inc. 146

Anypoint Platform Architecture Application Networks

API specification of the API. In other words, applying API policies often requires the RAML definition
or OpenAPI 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 owns the definition of reusable RAML fragments for all commonly used API policies in
Acme Insurance. These RAML fragments are published to Anypoint Exchange to encourage
consumption and reuse.

5.3.38. Latency overhead of applying API policies

Applying an API policy to API invocations adds processing overhead, which results in increased
latency (decreased response time) as seen by API clients. Depending on the type of API policy, that
latency is up to 0.38 milliseconds per HTTP request, as shown in Figure 85 [Ref15].

Figure 85. Increase in HTTP request-response latency through the application of various API
policies, which are enforced embedded in the API implementation.

Notes:

© 2020 MuleSoft Inc. 147

Anypoint Platform Architecture Application Networks

• The timings quoted in Figure 85 for the PingFederate access token enforcement policy exclude
the actual remote call to PingFederate
• Measurements for Figure 85 where performed using API Gateway 2.0, 1kB payloads, c3.xlarge
(4-vCore, 7.5GB RAM, standard disks, 1Gbit network)

© 2020 MuleSoft Inc. 148

Anypoint Platform Architecture Application Networks

5.4. Using Anypoint Security and Edge policies in

addition to Anypoint API Manager and API policies

5.4.1. Introducing Anypoint Security

• Anypoint Security can be used to implement perimeter defence in customer-hosted deployments
of the Anypoint Platform runtime plane (only) on Anypoint Runtime Fabric
• Comprises the functionality of a Kubernetes Ingress and also enforces Edge policies
◦ A Kubernetes Ingress provides load-balancing and SSL termination for external API clients of
APIs exposed by API implementations deployed to a Kubernetes cluster
◦ Anypoint Security includes Secrets Manager for storing the certificates needed for enabling
TLS traffic, optionally with mututal auth, to the Anypoint Security Ingress
• Looking at the Technology Architecture, Anypoint Security and Edge policies are independent of
Anypoint API Manager and API policies, but both can enforce a core set of similar NFRs (5.3.11,
5.4.2)
• Anypoint Security enforces Edge policies once for all APIs exposed from an Anypoint Runtime
Fabric Kubernetes cluster
◦ In contrast, API policies are enforced separately for each API implementation
• API policies on individual API implementations in Anypoint Runtime Fabric are typically enforced
as a 2nd line of defence

© 2020 MuleSoft Inc. 149

Anypoint Platform Architecture Application Networks

Figure 86. In a deployment of Anypoint Runtime Fabric with Anypoint Security as the Ingress,
external API clients access APIs exposed by Mule application API implementations via Anypoint
Security, which provides load-balancing and SSL termination and enforces Edge policies for all
these APIs. Additionally, Anypoint API Manager-defined API policies can be enforced within the Mule
runtimes to which these Mule applications are deployed.

5.4.2. Edge policies supported by Anypoint Security

Anypoint Security can enforce at least the following Edge policies:

• Content Attack Prevention (CAP) by limiting HTTP request properties: HTTP methods, header
size, body size, URL path length, … (cf. 5.3.23)
• Allowlisting of API client IP addresses, similar to IP-based access control in API policies (5.3.11)
• Web Application Firewall (WAF) security policy enforcing the OWASP Core Rule Set [Ref17],
including (configurable): SQL injection, cross-site scripting, local file inclusion, HTTPoxy,
Shellshock, session fixation, …
• DoS attack prevention through monitoring of API clients' HTTP requests, and rate limiting or
blocking their IP address upon detection of a DoS attack
◦ Other Edge policies and API policies can escalate policy violations to a DoS policy to
contribute to the detection of a DoS attack, as defined by rules in the DoS policy

© 2020 MuleSoft Inc. 150

Anypoint Platform Architecture Application Networks

5.4.3. Tokenizing sensitive information in API invocations

Tokenization is a security feature of Anypoint Security and is enabled by a Tokenization Service and
corresponding API policies (not Edge policies):

• Tokenization replaces sensitive information (credit card number, SSN, account number, any
regex, …) with a reversable token
• Detokenization restores the original sensitive information
• Typically configured to be format-preserving such that downstream systems' validation rules are
not violated
◦ 1234-5678-9012-3456 -> 9264-1956-3442-3456 (tokenization of credit card number,
configured to preserve format and keep last 4 digits)
• Applied to HTTP requests (Figure 87) or responses (Figure 88) sent to/from individual APIs by
configuring the Tokenization and Detokenization API policies via Anypoint API Manager on the
corresponding API instances
• Tokenization Service is deployed to Anypoint Runtime Fabric and these API policies delegate to it
the actual de/tokenization
• Anypoint Security implements vaultless tokenization, i.e., there is no "vault" (database) that
stores the original, clear-text values
• Tokens are not amenable to brute-force attempts of detokenization

Figure 87. Tokenization can be performed by the Tokenization API policy on the contents of HTTP
requests. Detokenization via the Detokenization API policy works analogously. Both API policies
delegate to Anypoint Security’s Tokenization Service.

© 2020 MuleSoft Inc. 151

Anypoint Platform Architecture Application Networks

Figure 88. Tokenization can be performed by the Tokenization API policy on the contents of HTTP
responses. Detokenization via the Detokenization API policy works analogously. Both API policies
delegate to Anypoint Security’s Tokenization Service.

© 2020 MuleSoft Inc. 152

Anypoint Platform Architecture Application Networks

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 API invocations and can impose NFRs on
that level in various areas
• API policies can be enforced directly in an API implementation that is a Mule application, in a
separately deployed API proxy, or via Anypoint Service Mesh
• Client ID-based API policies require API clients to be registered for access to an API instance
◦ Must pass client ID/secret with every API invocation, possibly implicitly via OAuth 2.0 access
token
• 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
• Anypoint Security can enforce Edge policies to implement perimeter defence in customer-hosted
deployments of Mule runtimes on Anypoint Runtime Fabric
• De/Tokenization can be applied to API invocation content by API policies that require Anypoint
Security

© 2020 MuleSoft Inc. 153