Global TechHubHome
Introduction
Given the importance and value that APIs
represent for numerous businesses, it’s important to consider API development
best practices when designing and building APIs using MuleSoft. The APIs that
have the most value and use for the enterprise are more like products than
code. They are designed to be consumed by specific audiences (e.g., mobile
developers), they are well-documented, and they are versioned so users can have
certain expectations of the API maintenance and lifecycle. API development best
practices enable the full API lifecycle from design, build, test, through to
deployment.
Overview
Anypoint Studio
Studio updates
Ø Keep your Anypoint Studio up-to-date (Install Studio Updates when
available)
Mule Runtime
Ø It’s really important the coherence of the Mule Runtimes version within
the SDLC. If you developed and tested your application using a Mule Runtime
3.9.0, deploy it to a worker with the same Runtime version.
Ø
Upgrade your projects constantly to
the latest patch-version 3.9.x/4.0.x/4.1.x
(Install the new Runtimes from the Studio Update Site or from the Mule
Runtime Update Site).
Ø If you want to migrate your applications to a minor-new-version or a
major-new-version (e.g. 3.9.x or 4.x) follow the migration guides provided in
the MuleSoft public documentation
Mule Projects in
Anypoint Studio
Ø Use Maven for creating a New Mule Project.
Ø
Include a .gitignore file in every
Mule Project.
Ø Add APIKit components getting the RAML from Design Center.
Project Files Structure
Ø Create a separate xml for the global elements (e.g. configuration
elements).
Ø
Create a separate xml for each use-case/functionality or resource-implementation.
Ø
Create a separate package for each use-case/functionality.
Ø
Create separate xmls for common
structures/logic.
Ø Create different packages for the resources (dataweave, wsdls, examples,
etc).
XML identation and formatting
Ø Define a line width in your Anypoint Studio XML editor preferences, e.g.
140
Ø Indent all your xml (mule xmls, pom.xml, log4j2.xml, etc) files before
committing to the source code repository
Properties per environment
Ø Use property placeholders to externalise properties. Use a placeholder in
the location-name of the file to identify the environment.
<context:property-placeholder location=”customer-api-${mule.env}.properties”
/>
Mule Components
Dataweave
Ø To transform/enrich the data, dates transformation and build
error/response messages instead of custom scripting code (Java, Groovy, etc)
Ø
When dealing with large payloads,
include the directive indent=false to improve the client’s parsing performance
and to reduce the response payload size.
Ø
Define the input content-type to
avoid verbosive messages in the Log e.g.
Ø Use inline dataweave scripts on the development phase, then pass it to an
external file to have a clean xml and reusable scripts.
HTTP Listener
Use the following placeholders:
Ø ${http.private.port} when deploying to CloudHub using HTTP and using a
Dedicated Load Balancer (http.private.port is a reserved key in CloudHub that
resolves to 8091)
Ø ${https.private.port} when deploying to CloudHub using HTTPS and using a
Dedicated Load Balancer (https.private.port is a reserved key in CloudHub that
resolves to 8092)
If HTTPS is required (e.g. in the DLB
upstream protocol or for the CloudHub shared load balancer) use the HTTP
Listener with a TLS Context reference, configuring the key-store with a
key-pair values generated with keytool.
HTTP Request
Request to APIs with self-signed certificates
When consuming APIs that are exposed with a
self-signed certificate, use the HTTP Requester with a TLS Context reference,
configuring the trust store with the self-signed certificate or including the
“insecure=true” attribute to avoid the certificate validation (useful when
running locally, don’t use this in prod).
HTTP Request Status Code Validator
By default the HTTP Request expects a 2xx
status code from the target system, if there’s a different status code in the
response it will throw an Exception. If you want to control different responses
by adding some business logic, you have to configure the range of status codes
considered as ‘valid’, by doing that you can put some logic after the HTTP
Request, e.g. a Choice to take decisions based on the status code.
Web Service Consumer
Ø Import the wsdls and the xsds in your project
Ø Use the Webservice Consumer component and point it to the local wsdl
Database Connector
Ø Use parameterized queries
Ø Use dynamic queries only if you don’t have another choice, remember to
validate the inputs previously (using dynamic queries could cause SQL-Injection
vulnerability
APIKit
Ø Use the APIKit features to generate the flows automatically
Ø
Use the APIKit Exception Strategy to
catch connector related exceptions
Ø
It’s a good practice to disable the
APIKit Console under all exposed environments (e.g. CloudHub environments,
production -onPrem) as:
o
If the API Console is used without
caution, you can affect real objects/data due to the fact that you don’t have a
‘mocking-services’ option. When using API Portals (Exchange Public/Private
Portal) you can enable mocking services.
o
If an API Portal exists, the API
Console is a redundancy.
o If there are no policies applied, the API Console is a risk, due to point
#1.
Validator
Ø Use Validator instead of throwing exceptions with Groovy Scripts
Flows Reusability
Ø Use Flow references to separate and reuse common logic. The flow diagram
should be clear, showing the steps of the use case.
SSL
Ø Always use HTTPS listeners, if your applications are exposed on the
internet or if you have internal security regulations. HTTPS can also be
terminated at load balancer level when using Dedicated Load Balancer or where
the user is hosting their own load balancer on-premises.
Ø In NYU, there is a Dedicated Load Balancer configured. HTTPS in listener
in Mule applications is not mandatory because the SSL termination is done on
the DLB.
Secure Application Properties
Ø Sensitive application properties such as access credentials and passwords
can be obfuscated in CloudHub by using the Secure Application Properties
feature.
Ø
Such feature can be used in
conjunction with the Mule Credentials Vault that allows users to encrypt
properties within the application properties files.
o
Use AES algorithm with a CBC mode.
o Define a 128 bits key, if you want to use a 256 bits key, the JCE
Unlimited Strength Jurisdiction Policy Files need to be installed in each
workstation
Java custom code/Scripting
Ø Only if there is no other choice.
Cache
Ø Use the Cache scope whenever possible, to wrap HTTP calls / flows / logic
that obtain/produce information that doesn’t change frequently
Ø Define a ttl (time to live) based on an analysis, it shouldn’t be
arbitrary
Unit and Integration Testing
Ø Create significative Unit tests using MUnit
Ø Create significative Integration tests using MUnit
Mule Deploy Maven Plugin
Ø Include the Mule Maven Deploy Plugin in each application
Debugging & Troubleshooting
Use Anypoint Studio Debugger to debug your
Mule Applications.
Wire Logging
To enable a more detailed logging to see all
the HTTP requests and responses, configure the following loggers in
src/main/resources/log4j2.xml
Naming Conventions
Category
|
Convention
|
Pattern
|
Examples
|
Mule
Projects
|
kebab-case
|
{domain}-{subdomain}-{layer}-{type}
{process-or-integration-name}
|
customers-sys-api
identity-sys-api
cloudhub-log-aggregator
|
Maven
Group Id
|
fixed name
|
edu.nyu
|
edu.nyu
|
Mule XML
files
|
kebab-case
|
{significant-name}.xml
|
customers-api.xml
delete-customer.xml
common.xml
|
Global
Elements
|
kebab-case
|
{significant-name}
|
http-listener-config
|
Mule
properties files
|
-
separated
|
{domain}-{subdomain}-{layer}-{environment}.properties
|
Customers-sys-dev.properties
|
Mule
properties keys
|
dot separated
|
NA
|
http.listener.host
|
Dataweave resources packages
|
package notation
|
{dw}.{classifier}
{dw}_{classifier}
|
dw
dw.customers
dw.customers.accounts
dw.health_check
|
Dataweave
Scripts
|
kebab-case
|
{significant-name}.dwl
|
build-error-message.dwl
|
JSON
Examples
|
kebab-case
|
{method}-{significant-name}-{request|response}-example
|
delete-customers-response-example
|
Mule
flows
|
kebab-case
|
{significant-description}-flow
|
send-user-to-queue-flow
|
API HTTP
base path (On Prem)
|
NA
|
{domain}/{subdomain}/{layer}/
{version}/*
|
/students/sys/v1/*
|
API HTTP
base path (Cloudhub)
|
NA
|
NA
|
/api/*
|
Conclusion
In this article, I have provided some basic
MuleSoft coding standards and naming standards. There is no such thing as a
naming convention for Mule. You could try to apply the same rules Mule
community developers follow, but those are not strictly for Mule Applications.
At the same time it does make sense to
follow the same naming conventions than the IoC container of Spring given that
Mule is a sort of specialization of it. Organization to Organization these
standards changes.
Download
S. No
|
File Name
|
Size
|
Download
|
1
|
MuleSoft
Development – Best Practices & Naming Conventions.pdf
|
1.0 MB
|
Comments
Post a Comment