14

Best Practices, Tips, and Tricks

In the previous chapters of this book, we’ve learned different aspects of designing, developing, and deploying Mule applications. We’ve learned about the different products that can be found in the MuleSoft suite and their purpose. We learned about Anypoint Platform, Anypoint Studio, Composer, and so on. However, there are still some best practices we’d like to compile for you. This way, you can take these into account when you’re working on your future applications.

In this chapter, we’re going to cover the following main topics:

• Best practices
• Tips and tricks

Let’s start by listing some of the best practices you can apply to your future projects.

Best practices

These are a set of rules you don’t necessarily have to follow in order for your applications to work properly, but are a huge help to guide you through what you can do to make your projects better. We will list different best practices ranging from design and development to some security and architecture tips.

As previously mentioned, you are not required to apply these rules to your projects or applications, but they will help you to be more successful with your projects. Feel free to take the ones that apply to you or modify some of them to better fit your needs. The purpose of this list is to help you build your own best practices based on these.

Let’s start with some general best practices.

General best practices

Here are some best practices that you can apply to your projects in general.

• Add a health-check endpoint: Create a specific endpoint, such as /ping, to get the API’s running status. This is helpful to monitor the API from an external tool if needed. You can simply create a new endpoint using the HTTP Listener connector and return a short payload that states this application is up. If the application is not available when you try to call it, it will not return the OK payload. This way, you’ll know there’s something wrong with the deployed application and you need to double-check it. You can also return more details, such as the name of the host or the time it took to process the response, depending on what you want to see when you send the request to this endpoint to ensure the status of the application.
• Follow naming conventions: You can create a set of naming conventions with your team so that APIs, files, flows, properties, and so on share the same standards and can be found more easily. For example, if you’re using an API-led connectivity approach, you can add eapi, papi, or sapi to the name of the API in order to easily identify whether it’s an Experience, Process, or System API. It can be as simple as naming your project something such as pshopping or it can be more complex if you have many APIs and want to be able to differentiate between them.
• Create unit tests: Follow the best practice of creating unit tests in MUnit as part of the development cycle. Each developer should be responsible for creating their own set of unit tests to ensure their code works as expected in different scenarios. Of course, you can have a specialized Quality Assurance (QA) team that can take care of other types of testing, such as regression or performance, but developers are the ones that are closer to the code, so it should be an expectation for them to create the unit tests for their specific code.
• Create a CI/CD pipeline: Whenever the code is pushed to specific branches, a Continuous Integration/Continuous Delivery (CI/CD) pipeline should be in place to release the new code in the specified environment. For example, when pushing code to the dev branch, a new deployment will be done to the dev environment. This should be created by the operations team (or DevOps), but if your company doesn’t have the roles, then the responsibility can be that of the developers or architects.
• Create separate VPNs: It’s a best practice to create a separate VPN for non-production environments (dev, QA, staging, and so on) and the production environment. This is added as a security measure in case anything goes wrong with the non-production environments’ VPNs so your production VPN is intact.
• Do not log sensitive data: In some cases, the information the API is handling is sensitive data, for example, credit card or social security numbers. It is best not to log these fields for security reasons. You can use other fields to log the information if you need, but make sure they don’t contain sensitive data, for example, first name or gender.
• Use standard logging and error handling: It’s best to use the same standard for all your APIs as much as possible. When developers already know how the logging and error handling works in the whole project, they won’t have an issue with working on a different API since the standards are the same. This also helps to keep all logging as secure as possible by not logging sensitive data or masking information. This helps to reduce development time and human error.

As you can see, the previous list was intended for projects or architectures in general. Let’s now go a bit deeper and list some of the best practices that you can apply to your Mule projects – the ones you create in Anypoint Studio to create Mule applications.

Mule project best practices

When you start a new project in Anypoint Studio in order to create a Mule application, you’re creating a Mule project. You have a pom.xml file, a main configuration file where your flows will be, some Log4j configuration, and so on. We will now list some of the best practices to create better Mule projects:

• Separate global elements: For easy access, create a file called global.xml or whichever naming convention your company has to keep all the global elements in this one file. This will reduce development time when trying to find a specific element and it also serves to not duplicate elements since they’re all listed in the same place. You can either create global elements in this file directly or move global elements from other files into this one. For a step-by-step guide, visit the following tutorial: https://developer.mulesoft.com/tutorials-and-howtos/getting-started/global-elements-properties-files/.
• Separate common flows: For easy access, create a file called common.xml or whichever naming convention your company has to keep all the common flows, logic, or functionality in one file. Same as the previous point, this will reduce development time when trying to find a specific common component since they’re all located in the same place. When we say common, we mean pieces of code (can be flows, subflows, or error-handling pieces) that are used in a number of flows or files across the project. For example, if you have an authorization flow that has to be used before calling an external API, you can consider this authorization flow a common piece since it’s referenced by several other flows scattered across different configuration files.
• Create a folder for each resource: Under src/main/resources, make sure you create a separate folder for each type of resource to find them more easily, for example, dataweave, wsdl, and examples. The same applies to the src/test/resources folder to keep your testing files. This is especially useful in bigger projects because you can get lost in so many files. But if you have the correct folders, following intuitive naming conventions, then it won’t be that hard to find the files you need by navigating to these folders.
• Never hardcode data. Use properties instead: When you hardcode certain things in the connectors, it’s harder to find and change them later, for example, credentials or URLs. When you use properties to keep this information, there is a single place where the data can be changed. It’s also better-looking in your repository at the time of reviewing a pull request. Instead of having to go through the different configuration files, you can just review the properties files.
• Separate properties files by environment: When you create properties files (either .properties or .yaml), make sure you create a separate file per environment to change the values of the properties depending on the environment the application is deployed in, for example, local.properties, dev.properties, qa.properties, and prod.properties. You can also separate the secured properties into different files and still separate them by environment, for example, local.sec.properties or dev.secure.properties, depending on your team’s naming conventions. To do this, you need to define a global property to know which environment you’re in. This property will change in each environment, which will tell the Mule application to take one file over the other ones. Note that this also applies to .yaml files if they are your preference over .properties files. For a step-by-step guide, visit the following tutorial: https://developer.mulesoft.com/tutorials-and-howtos/getting-started/global-elements-properties-files/.
• Encrypt secured properties: Make sure the sensitive properties you add to your Mule projects are securely encrypted. You can encrypt your properties using the Secure Properties Tool from MuleSoft and the application will be able to decrypt them at runtime with the Mule Secure Configuration Properties module, using the encryption key with which you encrypted the properties in the first place. To learn more about this, visit the following documentation page: https://docs.mulesoft.com/mule-runtime/latest/secure-configuration-properties. For a step-by-step guide, visit the following tutorial: https://developer.mulesoft.com/tutorials-and-howtos/getting-started/how-to-secure-properties-before-deployment/.
• Keep the encryption key separate: Never add the key you used to encrypt the properties (see the previous point) in your Mule application. This can lead to hackers easily decrypting all your properties. Instead, you can pass the key as an environment variable inside the Run Configurations section to run it locally and add it directly to the properties in Runtime Manager for each environment in CloudHub. For a step-by-step guide, visit the following tutorial: https://developer.mulesoft.com/tutorials-and-howtos/getting-started/how-to-secure-properties-before-deployment/.
• Hide your secured properties in Runtime Manager: Open your Mule application’s mule-artifact.json file and make sure you add the properties you want to hide to the secureProperties field. This will mask the properties in Runtime Manager so no one can see them from the UI. It won’t make a change for your properties in your local machine, but it is helpful from the UI’s perspective. For a step-by-step guide, visit the following tutorial: https://developer.mulesoft.com/tutorials-and-howtos/getting-started/how-to-secure-properties-before-deployment/.
• Externalize DataWeave scripts: When you use the Transform Message component in your Mule applications, the DataWeave script is automatically added to the XML file (or configuration file) where the component is located. It’s a best practice to keep an external .dwl file for your script instead of embedding it in the XML file. For this, just click on the Edit button inside your Transform Message component, select File (instead of Inline), add your folder name and filename (for example, dataweave/myscript.dwl), and click OK. Your files will be created under src/main/resources. If you have many Transform Message components and you notice it’s hard to find the dwl files, it’s best you create more folders to separate the script files by folder and find them more easily.
• Indent DataWeave scripts: In DataWeave, it’s not required to indent properly for the script to work, but it’s a best practice to keep the indentation when needed. For example, if you open a parenthesis and then create code on a new line, that new line should be indented to know it’s inside the parentheses. The same thing applies to new lines inside a function or a variable even though you might not have opening parentheses or curly brackets.
• Use data types in DataWeave: In DataWeave, it’s not required to assign data types; however, your code will have better quality if you get used to doing this on a daily basis. You can assign data types to variables, functions, parameters, and so on. This is also helpful to see the potential errors you might have at runtime before even getting to that point. To learn more about this, visit the documentation: https://docs.mulesoft.com/dataweave/latest/dataweave-type-system.
• Create a Mule project template: Create a Mule project that can be used as a template with the required structure, configurations, or dependencies. This way, the developers don’t have to create a new project from scratch but they can use this template as a foundation to create a new one with the needed structure already added.
• Use different workspaces: It’s good to keep different kinds of projects in different workspaces, especially if you work with a lot of Mule projects. This is also helpful to save separate settings in your workspaces, for example, personalize your own debug view or create a custom view. It’s also worth noticing that the cache is stored by the workspace (at least in Anypoint Studio). We will see why when we cover tips and tricks later in this chapter.

Now we have a better idea of what best practices are good to apply to your Mule projects. Some are more critical because of security issues that may arise, while others just provide a more comfortable solution to reduce development time.

Let’s now jump into some best practices when working in Anypoint Platform and the different products we can find there.

Anypoint Platform best practices

Anypoint Platform is where most of MuleSoft’s products are located. We start by designing APIs in Design Center, we deploy Mule applications in Runtime Manager, we secure our APIs in API Manager, and so on. Let’s list some of the best practices we should be using for some of these products:

• Apply automated policies: In API Manager, instead of applying policies to one API at a time, you can apply automated policies that will be added to all the APIs you select. This helps to reduce human error and keep a standard across all APIs.
• Enhance Exchange’s documentation: When you publish a resource to Anypoint Exchange, make sure you add clear descriptions, required images, and supported authentication in the API documentation. This will be helpful for other people who want to use your API.
• Define common API specification fragments: When creating the API specification in Design Center, make sure you create fragments for the repeating blocks and reuse them across the specification. This way, you don’t have to copy and paste the code every time you need it in a different place, reducing time and human error.
• Use common headers in the API specification: When creating the API specification in Design Center, you can use common headers to include the correlation ID, transaction ID, and so on. This way, similar information will be used across all APIs, which is helpful for the development team. This will help to improve tracing and correlation across different APIs.
• Use nouns for the API specification’s resources: When creating the API specification in Design Center, make sure you use nouns instead of verbs for the names of the resources, for example, /members instead of /getMembers. You can read more about best practices for your API specifications in this article: https://developer.mulesoft.com/tutorials-and-howtos/getting-started/best-practices-first-api-spec/.
• Use versioning in the API’s URL: It’s a best practice to add the version number to the API’s URL. There are different ways of doing this, but we recommend using the version before the resource path, like so: /v1/members.
• Create an API specification template: Create an API specification that can be used as a template with the standardized resources and shared fragments. This way, the developers don’t have to create a new API specification from scratch but they can use this template as the foundation to create a new one with the needed resources already added.

Most of these best practices apply to Mule projects in Anypoint Studio because it’s where most of the coding happens. The second place where we do most of the coding is when creating the API specification. As you just saw, most of the best practices for Anypoint Platform come from Design Center at the time you’re designing your API specifications.

Now that we know some general, Mule project, and Anypoint Platform best practices, let’s take a look at some tips and tricks for when working with MuleSoft’s products.

Tips and tricks

The following list of tips and tricks is not the same as the best practices list. Best practices are rules or standards that you can choose to follow to create a better developer experience or to avoid common mistakes. The following list gives you some advice that you may or may not be aware of but will help you to troubleshoot your applications more easily:

• Switch workspaces when needed: If you notice some weird behaviors with Anypoint Studio, for example, if the breakpoints aren’t working properly or the debugger does not work as expected, you can switch to a different workspace and import your project there. This works sometimes because the cache in Anypoint Studio is saved within each workspace. So, if the problem you’re experiencing is because of the cache, once you switch to a different workspace, the cache is brand new. This might help to resolve your issue with the IDE.
• Run more than one Mule project at a time: In Anypoint Studio, go to Run and then select Run Configurations. Here, you can create a new Mule application configuration and select more than one Mule project to launch at the same time. This will help you when you need to run the three API layers (Experience, Process, and System) on your local machine. You can use this configuration to either debug or run all applications. Just make sure all the applications you want to run are open in the same workspace.
• Monitor certificates: If your Mule application is using certificates, make sure you monitor the expiration date and renew the required certificate before it expires. Otherwise, your application will stop working because of security issues. This is good to keep in mind to avoid any future troubleshooting and save development time.
• Use the latest version of the connectors: When you browse for a connector in Exchange, make sure you use the latest stable version of it in your Mule applications. Sometimes there are bugs in previous versions that were fixed in the newest versions, so it’s best to keep up to date. If you already have a connector and you want to update it to the latest version, you have to make sure it’s a minor version and not a major version. Otherwise, you risk your code breaking or the functionality changing. If your code is compatible with the newest major version, then you can update the connector.
• Create custom error types when needed: It’s good to use the default error handling, but sometimes you need to provide more details to know what failed in your code. You can create custom error types to handle different scenarios, such as data errors, validation errors, or connectivity errors.
• Use error codes when needed: If you create custom error types for your applications and you have different errors for different scenarios, it’s useful to use the error code instead of the error description. This way, the calling application knows how to handle the given exception based on the error code, which should be unique.

We hope this list of tips and tricks is useful for your MuleSoft journey and your future projects. These are some things that have helped us in our career and we wanted to share them with you. You can create your own list with more things that have helped you and share it with others to expand the general knowledge on MuleSoft’s line of products.

Summary

In this chapter, we listed some best practices and tips and tricks that you will be able to apply to your future MuleSoft projects.

We talked about general best practices that may apply to different projects, such as integrations or APIs, as well as ones that are more high level. Then, we zoomed into actually talking about the things that are implemented in the Mule projects in Anypoint Studio. Finally, we discussed some of the best practices you can apply to your API specifications and other Anypoint Platform products, such as API Manager.

We also provided a list of some tips and tricks that have been helpful for us in our MuleSoft career. We encourage you to take this list and enhance it with your own tips, especially after trying out the new Mule products that we didn’t get to try in this book, such as Anypoint Code Builder (MuleSoft’s new IDE that hasn’t been released yet).

Questions

Take a moment to answer the following questions to serve as a recap of what you just learned in this chapter:

1. What is a health-check endpoint and why is it useful?
2. What is an example of sensitive data that you shouldn’t log in your application?
3. What is the global.xml file used for?
4. What is the best practice to separate your properties?
5. What is the best practice to keep your properties’ encryption keys?
6. What is the file you can use in your Mule project to hide your secured properties in Runtime Manager?
7. In Anypoint Studio, where is the cache for your Mule project saved?

Answers

1. A health-check endpoint is one that you create in your API to get the API’s running status. It is helpful to monitor the API when needed to make sure it’s up and running.
2. Credit card information or social security numbers.
3. To separate all the global elements into this one file to reduce development time when trying to find a specific element.
4. Separate them by environment, for example, local.properties, dev.properties, qa.properties, or prod.properties.
5. Never add the keys to your Mule application’s code. You can pass the key as an environment variable in Anypoint Studio for local runs or using Runtime Manager for CloudHub.
6. mule-artifact.json.
7. In each workspace.