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

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.

© 2018 MuleSoft Inc. 53

Anypoint Platform Architecture Application Networks

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 38. 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 application network.

4.2. Identifying APIs for the "Aggregator Integration"

product

4.2.1. Towards an application network

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

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

© 2018 MuleSoft Inc. 54

Anypoint Platform Architecture Application Networks

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

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

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:

© 2018 MuleSoft Inc. 55

Anypoint Platform Architecture Application Networks

• 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

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 40):

• "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)

© 2018 MuleSoft Inc. 56

Anypoint Platform Architecture Application Networks

◦ 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, …)
• "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

© 2018 MuleSoft Inc. 57

Anypoint Platform Architecture Application Networks

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

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

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

implementations
Figure 40 is an example of a pronouncedly fine-grained API architecture. A break-down of the

© 2018 MuleSoft Inc. 58

Anypoint Platform Architecture Application Networks

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

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]

© 2018 MuleSoft Inc. 59

Anypoint Platform Architecture Application Networks

• 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

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

© 2018 MuleSoft Inc. 60

Anypoint Platform Architecture Application Networks

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

© 2018 MuleSoft Inc. 61

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

© 2018 MuleSoft Inc. 62

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

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

© 2018 MuleSoft Inc. 63

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 RAML definition 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 RAML definition 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)
• RAML 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)

© 2018 MuleSoft Inc. 64

Anypoint Platform Architecture Application Networks

4.3.2. Defining RAML

See the corresponding glossary entry.

4.3.3. "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 RAML definition of the API is the most important way of expressing that
contract.

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

You document various aspects of the API as follows:

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

© 2018 MuleSoft Inc. 65

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 45. Documentation for the "Policy Holder Search PAPI", including its RAML definition,
documents the business service realized by the API, its SLA and non-functional aspects. API
documentation must also be discoverable and engaging, as it must be easy to access by API
consumers.

4.3.4. Using Anypoint Design Center to sketch and simulate a

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

© 2018 MuleSoft Inc. 66

Anypoint Platform Architecture Application Networks

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

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

© 2018 MuleSoft Inc. 67

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 47. 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.6. 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
RAML 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 RAML definition 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 a RAML definition.

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

© 2018 MuleSoft Inc. 68

Anypoint Platform Architecture Application Networks

• It separates consumer- and client-facing version (major version) from asset version (full
semantic version of the RAML definition artifact): 6.2
• It parses the RAML definition 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 RAML definition, such as the HTTPS mutual
authentication requirement for the "Aggregator Quote Creation EAPI".

Every change to the content of that RAML definition 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 48. 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.

© 2018 MuleSoft Inc. 69

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

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

4.3.7. 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 RAML definition 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.

© 2018 MuleSoft Inc. 70

Anypoint Platform Architecture Application Networks

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

4.3.8. Including an API Notebook for "Policy Holder Search

PAPI"
The API Notebook for an API makes use of the RAML definition for that API and provides an
interactive JavaScript-based coding environment that can be used to document interactions
with the API 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 RAML definition 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.

© 2018 MuleSoft Inc. 71

Anypoint Platform Architecture Application Networks

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

4.3.9. 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 52).

© 2018 MuleSoft Inc. 72

Anypoint Platform Architecture Application Networks

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

© 2018 MuleSoft Inc. 73

Anypoint Platform Architecture Application Networks

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

© 2018 MuleSoft Inc. 74

Anypoint Platform Architecture Application Networks

Figure 54. 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.10. Repeat for all APIs for the "Create quote for
aggregators" feature
Create rudimentary RAML definitions and corresponding Anypoint Exchange entries with API
Notebooks and API Consoles for all APIs needed for the "Create quote for aggregators"
feature.

© 2018 MuleSoft Inc. 75

Anypoint Platform Architecture Application Networks

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

4.4. Identifying, reusing and publishing APIs and API-

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

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

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

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

© 2018 MuleSoft Inc. 76

Anypoint Platform Architecture Application Networks

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"
• 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 56):

• "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)

© 2018 MuleSoft Inc. 77

Anypoint Platform Architecture Application Networks

◦ 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, …)
• "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, …)

© 2018 MuleSoft Inc. 78

Anypoint Platform Architecture Application Networks

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 56. 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 57):

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

© 2018 MuleSoft Inc. 79

Anypoint Platform Architecture Application Networks

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.

© 2018 MuleSoft Inc. 80

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

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

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

• The RAML definitions for the APIs capture the important functional and some non-functional
aspects in a preliminary fashion

© 2018 MuleSoft Inc. 81

Anypoint Platform Architecture Application Networks

• An entry in Acme Insurance’s Anypoint Exchange has been created based on each API’s
RAML definition, 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 58. 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 53 and Figure 55.

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

© 2018 MuleSoft Inc. 82

Anypoint Platform Architecture Application Networks

• Using Anypoint Design Center, 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

© 2018 MuleSoft Inc. 83