MuleSoft policies are offered as part of API gateway capabilities and can be applied to REST API in Anypoint API Manager. Whenever MuleSoft REST API is invoked by the user application, Mule runtime engine executes all the enforced policies in a defined order. Policies are invoked before the actual call is made to the backend API. Policy has pre and post steps to execute before and after invocation of underlying API. Finally, response is delivered to API caller.

MuleSoft provides inbuilt polices for ensuring security, compliance, transformation, troubleshooting, and quality of service. Such polices can be used to verify authentication, limit request volume, spike control of requests within defined time limit, caching, logging, header Injection and more. However, policy offerings are not just limited to inbuilt policies. MuleSoft also offers custom category for an organization to develop its own policies for aligning internal objectives. Custom polices may be used to alter or enrich requests before or respond after backend API calls, mask API responses, implement vendor specific validations, apply custom restrictions to certain methods of REST API and its calls, alter status code and message based on conditions.

Policies could easily be applied to any number of APIs without having to write API specific code. Policies are stored on Cloudhub exchange and are hence, available for all APIs to apply throughout an organizational domain.

Enforcing policy on an API (both inbuilt and custom policies) incurs latency. Simple to complex policies usually incur 10 to 100 (ms) of latency on a roundtrip of an API call. One must always verify if an SLA is met while using the policy for a required functionality.

Key Steps for Custom Policy Development:

1. Set up project using archetype commands
2. Develop Policy using Anypoint studio
3. Upload policy to Anypoint exchange and apply policy to API configuration in Anypoint manager
4. Test Policy

MuleSoft policy is an XML file deployed into API manager. Policies can be developed using standard steps provided by MuleSoft documentation. However, policies have limited development features to support complex logic. This article, is an attempt to help you write complex and advanced logic to extend functionality of custom policies using MuleSoft flows/DataWeave.

Use Case

Custom policies are useful for various scenarios. It is a common practice to add or remove certain fields, mask data based on caller authentication levels, change status code or alter headers in case underlying API cannot be changed. As part of this dry run, we will cover data masking policy, mask API response value for the matching keyword, policy to mask defined keyword when customer type matches with given criteria e.g., mask keyword ‘Mobile’ if customer type is ‘Individual’. Underlying API response contains a list of customers with customer mobile number, customer type and other details. Without policy enforced, API caller would receive plain JSON data of the customers list, whereas if policy is applied then based on defined criteria, data would be masked for satisfying conditions/keywords.

Architecture

1. Set up project using archetype commands

Step 1: Basic Configuration

POM and .m2/settings.xml configurations

• Add maven archetype repository to the settings.xml for maven to gather required files from repository

<profiles>
   <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>
 </profiles>

• Add exchange server details to the setting.xml servers section, in order to upload policy to Anypoint exchange later

<server>
     <id>exchange-server</id>
     <username>username</username>
     <password>password</password>
</server>

• Activate profiles in setings.xml; this will override any matching Id profiles in the POM file

<activeProfiles>
        <activeProfile>archetype-repository</activeProfile>
</activeProfiles>

Step 2: Generate policy project

• Create destination project for the policy on file system
• Go to that directory in the command line
• Execute the following command:

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

• Take organization Id from Mule account access management and provide suitable artifact Id/policy name
• Import project into Anypoint studio

Step 3: Generated files

The two files which are vital here are my-custom-policy.yaml and template.xml.YAML. my-custom-policy.yaml file renders policy configuration UI. Properties defined in this file are later used to accept the user input in Anypoint API manager. Template.xml file contains the actual logic of the policy and its behavior. Check MuleSoft documentation to familiarize yourself with policy terms and purpose of each file.

2. Develop Policy using Anypoint studio

Step 1: An XML Template

Generated template.xml file contains basic structure of the policy design. This file contains logic of actual implementation and policy behavior. Read the values provided by the user in policy configuration and use variables to hold values for such user inputs.

<set-variable variableName="varMaskKeyword"
                 value="{{{FieldToMask}}}"/>
<set-variable variableName="varCustomerTypeToMask"
		 value="{{{CustomerTypeToMask}}}"/>

First variable is assigned a keyword name, which will be masked and second variable contains name of category that requires masking. Let’s write choice condition to verify that both keyword and category are not empty (user has option at configuration level to keep input fields optional or mandatory in YAML file)

<choice>
<when expression="#[(!isEmpty(vars.varMaskKeyword default null) and 
                  !isEmpty(vars.varCustomerTypeToMask default null))]">
	<flow-ref doc:name="Flow Reference" doc:id="2d2ec0e2-c27e-4603-94bd-a7ac1fad707a" name="subflow-          
                  mask-api-response" />
</when>
</choice> 

Next, to accommodate masking logic, flow reference and dataweave are required. Logic explained in the following section.

Step 2: YAML File

Properties defined in this file are rendered in the policy UI; properties would be visible in Anypoint platforms. Generate policy project using maven commands as below:

Configuration:

  - propertyName: FieldToMask
    name: Provide field name to mask, field name case must match.
    description: Enter Key/Field name to mask all the matching fields in an entire payload.
    type: string
    optional: true
    allowMultiple: false
    defaultValue: "Mobile"
    
  - propertyName: CustomerTypeToMask
    name: Radio Buttons
    description: Property Description
    type: radio
    options:  #Defines radio button group
    - name: Individual
      value: Individual
    - name: Company
      value: Company
    - name: Agency
      value: Agency
    - name: NotApplicable
      value: NotApplicable
    optional: false
    defaultValue: Option1 value

Step 3: POM.xml file

Refer links in last section to understand about POM settings. Add the transform extension dependency and replace group Id and exchange URL group Id placeholder with organization Id for the selected environment and exchange URL group Id placeholder with organization Id for the selected environment.

Step 4: Write complex logic using flows and dataweave transform-extension as a maven dependency

MuleSoft dataweave scripting language is a powerful transformation and mapping engine, which provides limitless possibilities to handle any type of structured or unstructured payload format. This makes policies more meaningful and flexible in order to manipulate user requests/headers/body and responses. Policies, just like Mule applications, can make use of Mule extensions or plugins to extend Mule core capabilities.

Use flow-ref tag like mule flows. Then drag sub flow component on the design part of template.xml. Use components to achieve your targeted logic like below:

Mask keyword dataweave script:

Step 5: Error handling

For any kinds of failure, it is important for the policy to catch exceptions, route and log these exceptions in API console for troubleshooting. Following script caters to the exception handling part –

Exception Scenario 1: Exception in Pre-script / before calling underlying API

Any exception that occurs in pre-call to underlying API will result in failure and exception will be routed to the API console for further analysis. External call header information is still accessible, leverage request header/body to identify failure request in correlation with other entities.

Exception Scenario 2: Exception in post-script / after getting successful response from underlying API

Any exception that occurs post API call will result in failure and actual response payload from underlying API would not be delivered to the caller. Rather policy exception handler block would form the error response and send it back to the caller. Make use of API response header/body to identify failure request in correlation with other entities.

Exception Scenario 3: API error propagate

Any exception in API logic, which is handled but propagated from the API, will be caught by the policy exception handler block. In this case, policy supersedes the formatting of error response back to the caller.

Error Scenario 4: API error continue

3. Upload policy to Anypoint exchange and Apply policy to API configuration in Anypoint API Manager

Any exception in the API logic, which is handled and sent by the API, would not be caught by the policy exception block because it is treated as a normal response and would be sent back to the API caller.

1. Go to the project folder, open command prompt for windows, terminal for Mac
2. Run ‘mvn clean deploy’ command
3. Policy will get deployed to Anypoint Exchange
4. Go to the Anypoint Manager and apply policy to the API configuration

Policy in Anypoint Exchange –

5. Apply policy to the API configuration in API manager

6. Configure Policy as below

7. Check API console log to confirm policy has been applied and verify its version

4. Test Policy

1. Run API URL from postman or any other REST client
2. Verify API Response with masked data

[
    {
        "CustomerName": "Megatron",
        "CustomerId": "1001",
        "CustomerType": "Individual",
        "Phone": {
            "Office": "777-767-7676",
            "Mobile": "******"
        }
    },
    {
        "CustomerName": "Warner Bros. Entertainment Inc.",
        "CustomerId": "1002",
        "CustomerType": "Company",
        "Phone": {
            "Office": "652-757-4885",
            "Mobile": "632-452-5087"
        }
    },
    {
        "CustomerName": "Optimus Prime",
        "CustomerId": "1003",
        "CustomerType": "Individual",
        "Phone": {
            "Office": "555-125-7964",
            "Mobile": "******"
        }
    },
    {
        "CustomerName": "Booklight",
        "CustomerId": "1004",
        "CustomerType": "Agency",
        "Phone": {
            "Office": "444-654-3879",
            "Mobile": "451-415-2105"
        }
    }
]

Other helpful resource links: (external links are subjected to change)

https://docs.mulesoft.com/api-manager/2.x/policies-custom-landing-page

https://docs.mulesoft.com/api-manager/2.x/http-policy-transform

https://docs.mulesoft.com/api-manager/2.x/custom-policy-4-reference

Please note:  A full-fledged policy with multiple keywords, hierarchy and condition-based masking is offered as part MuleSoft integration solution suite developed by Enquero, for more information reach us at [email protected]