2. Safe Harbour Statement
● Both the speaker and the host are organizing this meet-up in individual capacity only. We are
not representing our companies here.
● This presentation is strictly for learning purposes only. Organizer/Presenter do not hold any
responsibility that same solution will work for your business requirements.
● This presentation is not meant for any promotional activities.
2
3. A recording of this meetup will be uploaded to events page within 24 hours.
Questions can be submitted/asked at any time in the Chat/Questions & AnswersTab.
Make it more Interactive!!!
Give us feedback! Rate this meetup session by filling feedback form at the end of theday.
We Love Feedbacks!!! Its Bread & Butter for Meetup.
Housekeeping
3
5. 5
●About the organizer:
○ MuleSoft Ambassador
○ Architect @Cognizant
○ 3xMule Certifications
○ Delivery Champion
○ GoToMarket Champion
●About Cognizant:
○ Cognizant is a global system integrator
○ Founded in 1994. It has 320.000 employees
○ More than 250 Mule projects
○ More than 1.000 MuleSoft certified consultants
Introductions
6. 6
● Introduction
● Designing RESTful reusable APIs
● How API-led fits in the picture
● Example use case
● Wrapping up
Agenda
8. 8
● MuleSoft wrote the paper “API-led connectivity” 7 years ago.
● Its core ideas have been adopted by thousands of integration
architects, developers … and even competitors
● Used properly can help solving really complex problems.
● However, most people that joins the MuleSoft community just
creates three layers of APIs by default. Always.
● They consider API-led a mantra and any deviation from this is
considered a taboo, a bad design.
● Blindly following any mantra always poses a risk.
● Let’s see this in an (oversimplified) example.
Are people using API-led correctly?
9. 9
● Suppose that a business user writes the following user story:
Case Study – Integrate Salesforce with SAP
As an Invoicing Manager, I want to read in SAP
contacts stored in Salesforce so when creating an
invoice in SAP I can find in the UI the person to
address it.
● With that little information, which is the solution that the average MuleSoft developer is probably going
to propose?
10. 10
Case Study – Proposed Solution
System layer
Process layer
Experience layer
Salesforce Contacts API
Contacts API
Contacts API
GET /contacts
GET /contacts/{id}
GET /contacts
GET /contacts/{id}
GET /contacts
GET /contacts/{id}
11. Case Study – Strengths and Weaknesses
Enterprise Architect
You are over-architecting; too many
artifacts. Most of your APIs are just pass
through that provide little value.
MuleSoft Developer
I have created three APIs to foster
reusability. I’ve been taught to avoid
creating monolithic APIs
Project Manager
You have consumed a lot of
vCores just to solve a simple
use case.
Infrastructure Operations
You are adding extra latency. Besides,
now, we need to take care of three
artifacts instead of just one.
12. 12
● The first principle every software engineer learn is
KISS (Keep If Simple, Stupid).
● Software systems work best when they are kept
simple.
● Avoiding unnecessary complexity will make your
system more robust, easier to understand, easier
to reason about, and easier to extend.
● However, there are very specific scenarios in
which more than 1 layer of APIs make sense.
● We will see in this session when to create more
layers when pragmatically makes sense.
Doing things right, keeping things simple
13. Back to the basics –
Designing RESTful reusable APIs
14. 14
The API Gateway pattern
API Gateway
Micro Service
Accounts
Micro Service
Providers
ERP / CRM Legacy
Mobile SPA SaaS Trading partners
REST REST SOAP Proprietary
API 1 API 2 API 3 API 4
• APIs should focus on security and never implement business logic; there are
lots of languages more suitable to do it.
• Most APIs are internal, used to communicate applications
• Some APIs are used to communicate with other trading partners
15. 15
Anatomy of a RESTful API
API Customers V1
/customers
GET POST
/customers/{id}
GET PUT DEL
/customers/{id}/addresses
GET POST
SCHEMAS
ListCustomers Customers
Resources / Collections (nouns in plural)
Methods (GET, POST, PUT, PATCH, DELETE)
Resources / Entities
Sub and Nested Resources
Schemas (Data Types) – JSON Schema
Versioning (v1, v2, v3)
Adresses Errors
16. 16
Backward compatibility do’s
• Add new body parameters in a response
• Add new resources and methods
• Add new optional headers and query parameters
Backward compatibility don’ts
• Remove resources or rename them. Remove methods
• Convert parameters in mandatory
• Change dates format
Multi version
• Only as a last resort, go with v2, v3
• Most integration platforms (including MuleSoft) support
running several versions.
APIs are reusable by design
17. 17
Companies are creating reusable core APIs
Risk domain
Loans domain
Accounts domain Sales domain
Position API
Accounts Receivable
API
Fraud Diagnosis API
• Core APIs should be organized around business capabilities, never around tools, using a Domain Driven Design
approach
• An Ubiquitous Language is structured around the domain model and used by the team members within a Bounded
Context.
• A composable enterprise supports the changing demands by assembling and reassembling APIs
• There are already some industry standard models such as IATA Open Air, TMForum, OpenInsurance, BIAN, PSD2, etc.
• API specs are published in the API Developer Portal
Loan API
Corporate Lease API
Deposit Account API
Financial Control API
Operational Risk API
Compliance Reporting
API
Customers API
Products API
Campaigns API
18. 18
Backend For Front-end pattern
API Gateway
Core API
1
Core API
2
Core API
3
Data A Data B Data C
API Gateway
Core API
1
Core API
2
Core API
3
Data A Data B Data C
API BFF
BFF allows reducing the
chattiness of a SPA or
mobile application,
improving performance
GraphQL is today the most
promising language for BFF
20. 20
Can BFF + Core API converge with API-led?
System layer
Process layer
Experience layer
API
API
API
Domain 2
Domain 1
Core API
Core API
Core API
Core API
API BFF API BFF
21. 21
This is the only mandatory layer
• Core APIs or Business APIs are the only mandatory artifacts
• All other artifacts are just optimizations that can be built only if necessary
How these APIs interact with backends?
• Typically using HTTP. Today most enterprise solutions already provide an API.
• Also using proprietary protocols and connectors (SAP, AS2)
• If necessary, invoking an intermediate API
How this maps to API-led layer?
• The most close concept is Process API
• However, the term “process” suggests a “series of actions” that is not always
present in a Core or Business API
How to deal with domains and business capabilities
• Using Business Groups
• Using worker naming conventions.
Our first focus should be building Core APIs
22. 22
This is a perfectly valid software architecture
Process APIs
Micro-services
backend
AWS APIs / Azure
APIs
ERP / CRM Legacy /
Mainframe
Mobile SPA SaaS Trading partners
REST REST SOAP Proprietary
API 1 API 2 API 3 API 4
23. 23
Using System APIs
Are you saying that
System APIs are not
mandatory? Is it always
a good practice to
invoke directly the
backends from the core
(process) APIs?
24. 24
Using System APIs
Today, modern commercial off-the-shelf software solutions are expected to expose REST APIs. In the near
future, connectors for proprietary protocols will only be required in rare exceptions. There is no need to
create an extra System API just to wrap a call to an API that is already RESTful.
However …
Address security Error handling
Reduce
complexity
Improve third party
APIs.
… system APIs can still be useful:
25. Using System APIs to address security issues
System API
Process API 1
Whitelisted IPs
SaaS Backend
10.90.20.34
15.87.45.32
Process API 2
Process API 3
Static IP
Static IPs are a very scarce resource in CloudHub (2 x
number of vCores). By creating a System API that
centralizes access to SaaS backends, the number of
required static IPs is smaller.
AWS EC2
public IP
26. 26
Using System APIs to address security issues
System API
Process API 1
Process API 2
Process API 3
Object Store
SaaS Backend
Oauth
token
Oauth endpoint
Business endpoint
clientId /
Secret
clientId /
Secret
clientId /
Secret
System APIs can be useful to hide security complexity. By using an Object Store, System APIs can
automatically maintain an Oauth token and refresh it every few minutes. Process API can use simple
security mechanisms, like ClienID / Secret. Other systems like AWS force consumer to use a very complex
signature process based on canonicalization of parameters.
AWS API
AWS Signature
27. 27
Using System APIs to improve error handling
System API
Process API 1
Process API 2
Process API 3
AnyPoint MQ Retry API
Backend
Log 1
Log 2
Payload,
headers
By using System APIs, it is possible to send a message to Anypoint MQ whenever the backend is unavailable, so the
operation can be retried later. They are also useful to unify the logging for the same backend.
3
5
6
1
2
1
1
4
28. 28
Using System APIs to reduce complexity
System API
Process API 1
Process API 2
Process API 3
SaaS Backend
WSDL1
WSDL 2
Invoke SOAP
convert JSON
Invoke second
SOAP
Transform dates
and currencies
When the API exposed by the third party is not easy, or there are too many steps required just to obtain a
piece of data, it is better to remove that complex code from the Process APIs and concentrate it in a System
API. Besides, when using gitflow, the complexity of the feature branches gets reduced, as the System API
takes care of dealing with the complexity of the SaaS API.
29. 29
Using System APIs to improve 3rd party APIs
System API
Process API 1
Process API 2
Process API 3
SaaS Backend
POST /readInvoices
POST /deteteInvoices
POST /createInvoices
/Invoices
GET
POST
DELETE
{
INVOICE_NAME : “Shipment01”,
INVOICE_ADDRESS: “Wall Street 12”
}
{
name : “Shipment01”,
address: “Wall Street 12”
}
Some APIs of commercial off-the-shelf software solutions are very bad designed: crazy endpoint names with verbs
(!?), use of inappropriate methods, payloads with bad names or XML, dates in strange formats, bad usage of HTTP
codes, etc. By creating System APIs, those APIs can be improved, simplifying Process APIs.
30. 30
What about Experience APIs?
Ok, so System APIs can
be useful to solve
specific problems.
What about Experience
APIs? Should I use
them?
31. 31
Using Experience APIs
There is nothing wrong when a consuming application invokes directly a core API (process API)
or when a third party system makes a call to a core API. However, there are specific cases in
which it could be a good idea to add an intermediate API between the consuming application
and the core API. Typically, these experience APIs are created months or years after the core
APIs are created, on a as-needed basis.
BFF
Adapt to
SaaS
Security
32. 32
Using Experience APIs - BFF
Process API 1
Experience API (either using GraphQL or plain old REST) can be very useful to reduce the number of round-trips. In
addition, sometimes core API (process API) do not provide features crucial for UI like pagination, sorting, filtering, etc.
Process API 2
Experience API
[
{
name : “Airline”,
address: “Wall Street 12”
},
{
name : “Airline”,
address: “Wall Street 12”
}
]
GET /customers
GET /contracts?customerId=123
[
“contract: Maintenance”
]
[
{
name : “Airline”,
address: “Wall Street 12”
contract: “Maintenance”
},
{
name : “Airline”,
address: “Wall Street 12”
contract: “Maintenance”
}
]
GET
/customers?sortBy=name&pa
geSize=5&city=NewYork
33. 33
Using Experience APIs – Adapt to SaaS
Process API 1
Experience API
{
contract : “Maintenance”,
duration: 12
startDate: “2021/01/01”
},
Sometimes, some commercial off-the-shelf software solutions have limited call out features and they expect a specific
payload to be returned from the API. Although it is always possible to adapt the core API to support multiple formats,
in those cases it is a good idea to create a separate API to handle those exceptions.
SaaS {
contractDetails: {
topic : “Maintenance”,
init: “2021/01/01”
end: “2021/12/21” }
},
34. 34
Using Experience APIs - Security
Process API 1
Experience API
{
contract : “Maintenance”,
duration: 12
startDate: “2021/01/01”
price: 345000,
currency: “USD”
},
{
contract : “Maintenance”,
duration: 12
startDate: “2021/01/01”
},
Experience APIs can be used also to trim the payload, removing some fields that are sensitive and should not be read
by specific consumers. Again, this could also be implemented in the Process API, adding the logic in the API so with
DataWeave, part of the payload is removed in case the consumer does not have permissions.
Trading partners
35. 35
Using Experience APIs - Security
Experience APIs can also be used to create an API protected with different security policies. For example, core API
(process API) can be protected with clientId / Secret or Basic Authentiation, but Experience API can be protected with
OAuth or JWT tokens.
Process API 1
Experience API
Oauth API
Oauth / JWT
policy
Client credentials
policy
GET /authorize
POST /token
GET /endpoint
Header Authorization
Bearer TOKEN
GET /endpoint
Header ClientID / Secret
37. 37
● Customer is a global pharma company.
● Company has several systems:
● Some legacy custom backends that expose web services
● SAP
● SaaS applications (Salesforce, Workday, Coupa)
● Java Spring micro-services in AWS EKS.
● Customer is using MuleSoft Cloudhub to create APIs.
Meet the customer
38. 38
● Laboratory APIs to wrap the logic of existing micro-
services
● Payments API using PayPal
● Order APIs consuming data from SAP
● Warehouse API consuming legacy backend exposing SOAP
● Salesforce and third party to consume those APIs
Phase 1 – Initial set of APIs
Solution
● Invoke directly the micro-services in EKS as they
expose REST endpoint
● Invoke directly the PayPal API, as it is very well
designed and documented
● Invoke SAP using SAP Connector
● Invoke legacy using Web Services Consumer
40. 40
Phase 2 – AWS, Workday
● Expenses API using a backend that exposes a
complex a bad designed API
● A Credentials API consuming AWS Secret
Manager APIs that need AWS signature
(canonical data)
● An Employees API on top of Workday that
whitelist the consumers
Solution
● Create a specific API on top of the SaaS
application to encapsulate the calls
● A specific API with the logic to create the
AWS signature
● An API to interact with Workday in which an
Static IP is applied
42. 42
Phase 3 – Coupa, Mobile app
● Coupa needs to send data to SAP but it
cannot control the payload that sends
● A new mobile application that needs to
consume Payroll data but with complex
paginated searchs.
Solution
● Create an experience API that is tailored to
receive the payload that sends Coupa and
send its to SAP using Invoices API
● A Data Graph (GraphQL) that reuses existing
Process API and includes the ability to select
the fields to send to the mobile app.
45. 45
Primary goal is always to create core or business APIs around functional domains or business capabilities.
Core or business APIs are typically referred in MuleSoft API-led as Process APIs
If a consuming application can directly interact with a Process API, or a backend is already exposing a
good API, it is not required to add extra artifacts
Sometimes, specific use case need using extra APIs. For example:
Whitelisting IPs
Security issues (tokens, hiding fields, etc)
BFF – Aggregating REST APIs, using if possible GraphQL
Key take aways
46. 46
● Organize APIs around business domains and
capabilities, not tools https://apihandyman.io/organize-
apis-around-business-domains-and-capabilities-not-
tools/
● Deep Down into API-Led Architecture
https://www.ms3-inc.com/api-deep-dive/
● 5 integration patterns to debunk the myths about API-
led connectivity - https://blogs.mulesoft.com/api-
integration/patterns/patterns-to-debunk-api-led-
connectivity-myths/
Some interesting Links
48. Take a stand !
18
●Nominate yourself for the next meetup speaker and suggest a topic as well.
49. 20
● Share:
○ Tweet using the hashtag #MuleSoftMeetups
○ Invite your network to join: https://meetups.mulesoft.com/surat/
● Feedback:
○ Fill out the survey feedback and suggest topics for upcoming events
○ Contact MuleSoft at meetups@mulesoft.com for ways to improve the program
What’s next?