We would like to thank Sue Han for their contribution to this developer tutorial.
API Manager within Anypoint Platform comes with default policies you can apply to any APIs in your organization. In addition, you can also develop and apply custom policies in API Manager to extend existing functionalities.
Applying an API policy using API Manager would allow you to:
In this tutorial, we will walk you through the basics of developing and implementing a custom policy. You will learn how to:
Check out the existing default policies to see if a policy you would want to implement is already available.
We will be developing and implementing a Circuit Breaker custom policy. A circuit breaker policy allows you to put a fail-safe into your API-led design so that if there is a failure (i.e. Database is down), the connection is shut down to prevent the following:
For the purpose of this exercise, we will start with an empty project and add different portions of the code in the repository linked above to get a feel for the steps required from the beginning to the end.
Organization ID
, Client ID
, and Client Secret
- You can get the necessary information via the following:
java -version
and mvn -v
.For the purposes of the tutorial, we are using example APIs found in Anypoint Exchange: Hello World (we’ll call it HelloWorldAPI
) and Tutorial: Implementing a Custom API Policy in API Manager (we’ll call it HelloCircuitBreakerAPI
). The Hello Circuit Breaker API makes requests to the Hello World API. We will apply and test the custom policy on the Hello Circuit Breaker API.
hello-circuit-breaker
HelloWorldAPI-yourusername
)HelloCircuitBreakerAPI-yourusername
). Remember it needs to be unique throughout CloudHubYou can change from Table view to Text view to just copy and paste the text instead of adding each property one by one.
1
2
3
4
anypoint.platform.client_id=<your-client-id>
anypoint.platform.client_secret=<your-client-secret>
api.id=<hello-circuit-breaker-autodiscovery-api-id>
http.request.host=<hello-world-api-url>
After both APIs in Runtime Manager are deployed, use a REST client to check that the API can be called. Use the URL you copied for this last API (HelloCircuitBreakerAPI
) and add /hello
to the end.
For example, if your CloudHub URL was hellocircuitbreakerapi.us-e2.cloudhub.io
, then the URL you’d call would be hellocircuitbreakerapi.us-e2.cloudhub.io/hello
. You should receive a Hello World! message in the response.
Your hello-circuit-breaker
API from API Manager should now have an API Status of Active. We connected the HelloCircuitBreakerAPI from Runtime Manager to this API in API Manager by using the Autodiscovery API ID. To learn more about setting up Autodiscovery for your Mule applications, check out this developer tutorial.
We sill now configure Maven’s settings.xml
to specify:
Open Maven’s settings.xml
file which can be found in the .m2
directory.
C:\Users\<user>\.m2
${user.home}/.m2
If you don’t find this file in the .m2
folder, you can create it manually. You can take this settings.xml
file as an example and just change the credentials.
Add the credentials you use to log in to Anypoint Platform to the servers
section and the Nexus Enterprise Account. It should look similar to this:
1
2
3
4
5
6
7
8
9
10
<server>
<id>MuleRepository</id>
<username>your-nexus-username</username>
<password>your-nexus-password</password>
</server>
<server>
<id>exchange-server</id>
<username>your-anypoint-platform-username</username>
<password>your-anypoint-platform-password</password>
</server>
If you’re basing on your own settings.xml
file, make sure you include the following profile
configuration:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<profile>
<id>archetype-repository</id>
<repositories>
<repository>
<id>archetype</id>
<name>Mule Repository</name>
<url>https://repository-master.mulesoft.org/nexus/content/repositories/public</url>
<releases>
<enabled>true</enabled>
<checksumPolicy>fail</checksumPolicy>
</releases>
<snapshots>
<enabled>true</enabled>
<checksumPolicy>warn</checksumPolicy>
</snapshots>
</repository>
</repositories>
</profile>
<profile>
<id>Mule</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>MuleRepository</id>
<name>MuleRepository</name>
<url>https://repository.mulesoft.org/nexus-ee/content/repositories/releases-ee/</url>
<layout>default</layout>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
</profile>
Save your settings.xml
file.
To gather all the required files and set up the Mule project to create a custom policy, we will be using a Maven archetype provided by MuleSoft.
${orgId}
with the Anypoint Platform Organization Id we previously retrieved and ${policyName}
with the desired name for the custom policy. For example, circuitbreakerpolicy
.1
2
3
4
5
6
7
8
mvn -Parchetype-repository archetype:generate \
-DarchetypeGroupId=org.mule.tools \
-DarchetypeArtifactId=api-gateway-custom-policy-archetype \
-DarchetypeVersion=1.2.0 \
-DgroupId=${orgId} \
-DartifactId=${policyName} \
-Dversion=1.0.0-SNAPSHOT \
-Dpackage=mule-policy
Before finishing, Maven will ask you to define policyDescription
and policyName
which you can specify to describe and name your policy. For example, Circuit Breaker custom policy in MuleSoft
and Circuit Breaker policy
. Finally, just input Y
to confirm the properties are correct. After running the command, the project’s directory will have the following file structure with four files:
1
2
3
4
5
6
7
8
<policyName>/
├── <policyName>.yaml
├── mule-artifact.json
├── pom.xml
└── src
└── main
└── mule
└── template.xml
To learn more about this Mule project’s files, see Custom Policy Development Reference.
We will now update pom.xml
, <policyName>.yaml
, and template.xml
files to create our circuit breaker custom policy.
1 - Open the pom.xml
file
2 - Inside the properties
field, add the following snippet to specify the Mule Object Store version. In this particular custom policy, we are using the Mule Object Store Connector to retrieve and store values - in this case, counters - for up to 30 days.
1
<os.version>1.2.1</os.version>
For more information on Object Store, see Caching in a Custom Policy for Mule 4.
3 - Replace the dependencies
field with the following snippet:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<dependencies>
<dependency>
<groupId>org.mule.connectors</groupId>
<artifactId>mule-objectstore-connector</artifactId>
<version>${os.version}</version>
<classifier>mule-plugin</classifier>
</dependency>
<dependency>
<groupId>com.mulesoft.anypoint</groupId>
<artifactId>mule-http-policy-transform-extension</artifactId>
<version>${http.policy.transform.extension}</version>
<classifier>mule-plugin</classifier>
</dependency>
</dependencies>
4 - Replace the contents of template.xml
(inside src/main/mule
) in your project with this template.xml.
5 - Replace the contents of <policyName>.yaml
in your project with this circuit-breaker-mule-4.yaml.
6 - Ensure all the files are saved before moving on to the next step.
We will now package and deploy the custom policy to Anypoint Exchange, MuleSoft’s marketplace for connectors, templates, examples, and APIs, from where you can share and reuse this policy.
From the command line in your project’s root folder, run the package command.
1
mvn clean package
If the build is successful, publish the policy to Exchange from the command line in your project’s folder.
1
mvn clean deploy
Now, we will check that the policy is published to Exchange and import it into our Environment.
1 - On Anypoint Platform, go to Exchange and check that the policy is present. The type of the asset should be Policy and the name should be the policyName you previously provided when running the Maven archetype command.
2 - Go to API Manager and select the API that you want to apply the circuit breaker policy to. In this case, the hello-circuit-breaker
API.
3 - Once on the API version page, go to Policies > Apply New Policy.
4 - In the pop-up, you should see your Circuit Breaker custom policy listed with the label Custom. Choose the latest version (1.0.0) and then click on the Configure Policy button.
5 - The configuration page for the policy should pop up. Here are some values you can use to test:
Field | Value |
---|---|
Failure Threshold | 3 |
Retry Period | 30 |
Evaluate the error object to trigger the circuit? | TRUE |
Exceptions Array | "HTTP:TIMEOUT" |
Evaluate the HTTP response to trigger the circuit? | TRUE |
HTTP Codes Array | "500" |
Now your API has the custom policy applied!
1 - To test if the custom policy is working as expected, first call the API in a REST client.
2 - Stop the Hello World API from Runtime Manager by going to Settings > Stop.
3 - Once it stops, call the Hello Circuit Breaker API from a REST client once more. Before the failure threshold is reached, the state will say CLOSED
.
4 - Continue sending the same request until the threshold is reached. When the failure threshold is reached, the state will respond with OPEN
which means that the API will no longer make calls to the Hello World API and is working as expected. If a new incoming request arrives, the policy will reject it immediately.
Once the Hello World API is turned back on, the “Hello World”
string will be returned once again.
In this tutorial, we walked through the basics of developing and implementing a custom policy. You learned how to:
You’ve now developed and implemented your first custom API policy on API Manager. For more information on Custom Policies, see API Manager - How to Create Custom Policies - Friends of Max Demonstration.
To learn more about this circuit breaker policy and other patterns like CQRS and event-sourcing, see Implementing modern architectural patterns with MuleSoft.
Do you have any questions about the Mule project generated using the Maven archetype? You can compare your Mule project with ours to make sure everything was set up correctly.
You can also compare our settings.xml
file with yours in case you missed it earlier in the tutorial.
Start your 30-day free trial of the #1 platform for integration, APIs, and automation. No credit card required. No software to install.
Questions? Ask an expert.