Blog: Migrating Projects to Mule 4

Throughout the last three years of an engagement with one of our customers, we’ve migrated many interfaces to Mule 4. In this blog, I’ll share insights into my experience working on the design and development of Mule 4 interfaces.

Where do we start?

During the migration process, we consider many changes to and refactoring of the old code in order to accommodate best practices and improvements for well-known issues. There also might be different or new functional and non-functional requirements requested by the customer to be implemented on these new interfaces. That’s why, for those projects, we don’t use the migration framework provided by MuleSoft. 

So what do we do? The first thing in the migration projects is to study old code and documentation related to the interfaces that we’ll be migrating. Mule 3 projects can be opened in Anypoint Studio 6, which can be downloaded from the MuleSoft website. In fact, there are many useful things we can extract from the existing code: 

• The logic of how functional requirements have been implemented so far.
• API specifications written in RAML.
• Data transformation done in DataWeave.
• Error handling strategy. 

When writing code in Mule 4, API specification can be migrated from RAML 0.8 to RAML 1.0 in addition to data transformation (from DataWeave 1.0 to DataWeave 2.0).

In terms of documentation, it should consist of (at the very least) source and target systems used in the previous integration, input/output data and any mappings that are involved between the input and output. It’s also important to have an overview of the process. Pro tip: having a diagram helps immensely!

Now, let’s talk about not breaking things.

When migrating an old interface, we need to make sure that we make the minimal amount changes as possible for implementation by the consumers. The way we achieve that? We make sure that the new API that interacts with the client application accepts the same request body, and sends back the same response. In this case, also honour the same resource names as used in the old API. Looking at the old specifications will help.

Gathering requirements

After studying the ‘old’ process, now is the time to gather functional and non-functional requirements for the new solution. Functional requirements are often similar to the ones from previous integration; however, they need to be clearly defined. Many times, the non-functional requirements are different – it may be a new requirement to use APIs that are common to all other interfaces developed in Mule 4, for example, an API which provides auditing features.

Customers may also want to use some automated policies to be imposed on their APIs after being deployed. The logging strategy may also be different for the new APIs. The list of non-functional requirements can be quite long, so the important bit is to have everything documented when migrating projects.

Improvements

Once we have our functional and non-functional requirements documented, it’s time to look at the flaws of the old process. The new approach could be splitting the existing interface into separate APIs using an API-led approach. 

To illustrate this approach, let’s look at an example of a point-to-point integration, which was used to fetch orders data from the database using query parameters. To split this integration into API layers, we can make an experience API that will accept query parameters, use it to query data from the database and send back the appropriate response to the consumer. Then, we can introduce a system API that will be responsible for querying data from the database. The API-led diagram below shows this integration split into layers using an API-led approach.

One of the major advantages of the API-led approach is driving reuse into new application networks. By splitting the APIs into three layers (or two, in our case) later on, we can later reuse those APIs in different projects by quickly plugging them in. Looking at the diagram above, we can reuse system APIs everytime we need to query data from the database.

By introducing an experience API, we ensure the response sent back is as expected by our customer, with minimal changes introduced. We can also improve security by adding the policies to the APIs from the experience layer and improve performance, for example by adding different performance-related policies to the system APIs. It’s also important to mention that splitting the monolithic interface into separate APIs improves load balancing.

Other improvements to consider are resolving commonly occurring issues in the previous interface, among other changes that are important for our customers, or implementing queuing mechanisms to provide asynchronous communication and more reliability into the new process. One example of an improvement which we did for our customer was migrating them from Azure SQL Database to Azure Cloud Storage.

Solution and development

Now that we know the ins and outs of the old interface, and have all functional and non-functional requirements as well as improvements to make, we can start working on the API design solution of the new interface. It’s important to start with a high-level design. During this process, it’s essential to identify any APIs that can be reused or extend ones that have similar functionality. At this point, we also must find appropriate names for the APIs by following naming conventions.

Next, we can start working on low-level design and document it thoroughly using sequence diagrams. We need to document all the details related to the integration such as:

• Resource names
• Requests
• Response details (such as body, headers or query parameters) 
• Mappings
• Connectivity details
• Etc. 

Well-documented design is key!

Once the design is finalised and signed off by the customer, the development process will start, and we are able to implement all the requirements in Mule 4. Following all best practices and standards is vital, some of which are already defined by the customers at this point.

Conclusion

Migration projects are often a challenging process. However, having clearly defined functional requirements and non-functional requirements, as well as well-documented design are crucial to make the development process less troublesome. Using the capabilities of Mule 4 and Anypoint Platform, it is exciting to see just how straightforward it is to migrate projects!