Domain Support for Mule 4 API Proxies

Mule runtime engine (Mule) enables you to share common resources among Mule applications by defining these resources within a Mule domain. Other Mule applications can then inherit this domain.

Your Mule applications, when accordingly configured, can access the resources declared in your domain.

Because every autogenerated proxy is a preconfigured Mule application, you can define multiple API proxies under the same domain. You create a domain when you auto-deploy multiple proxies that use the same host and port but have a different path:

Domains Used by Proxies

API Proxies and Domains Overview

API Manager enables you to automatically configure an API proxy to inherit an existing domain. All API proxies use one of the following listener configurations when referencing a domain:

  • For inbound HTTP endpoints: api-proxy-listener-http

  • For inbound HTTPs endpoints: api-proxy-listener-https

Note that domains used by APIs are not supported by Runtime Fabric or CloudHub support domains.

Important: You may define several dependencies in a domain. Ensure that the versions of the dependencies defined in the domain have the same or later version than the ones defined in the API proxy that references the domain.

All the dependencies defined in the domain override the dependencies defined in the API proxy (older or newer). For example, if the API proxy depends on a functionality defined in the HTTP transport, but is referencing a domain using an older version of that transport, errors are thrown at runtime.


API proxy listeners must inherit your domain HTTP listener configuration by using the listener configuration defined in the target domain.

The following code illustrates the HTTP listener configuration defined in a target domain:

<http:listener-config name="api-proxy-listener-http">
  <http:listener-connection host="" port="8081" protocol="HTTP"/>

For HTTP listener configuration defined in the domain, the listener setup on the API proxy must be defined as:

<http:listener config-ref="api-proxy-listener-http" path="${proxy.path}" responseStreamingMode="AUTO">

Configure the Domain Used by an API Proxy

To configure the domain used by an API proxy:

  1. Select API Manager > API Administration > Manage API.

  2. Based on the source from where you want to import the API, perform one of the following steps:

    1. To import the API from Exchange, Select Manage API from Exchange.

    2. To import the API from your local machine, select Import.

  3. Specify an API name, Asset type, API version, and Asset version.

  4. In Managing Type, select Endpoint with Proxy, and then in Proxy deployment target, select Hybrid.

  5. In Mule Version, select the Check this box if you are managing this API in Mule 4 or above checkbox.

  6. In Implementation URI, type your API URI.

  7. If you plan to have HTTPS communications, specify a TLS Context.

    The path for your implementation URI if it is different than /.

  8. Click the Advanced Options expander list.

  9. Select your schema (HTTP or HTTPS) and optionally specify an API instance label.

  10. Specify the port for your API proxy inbound connections, and optionally set a response timeout.

  11. Select the Reference User Domain checkbox.

  12. Click Save:

    proxy domain support bb01e
  13. After saving the API proxy configuration, perform one of the following steps:

    • Deploy the API proxy to the selected target (Settings, under Deployment Configuration).

    • Download the API proxy (Actions) and edit it in Anypoint Studio to customize your target domain before deploying it.

Configuring a Domain for the First Time

When referencing a domain, Mule reads the domain Maven coordinates from the API proxy pom.xml file and looks for an already deployed domain with the same semantic name. For example, in the case of an API gateway domain with the version specified in the previous example, the semantic name is: gateway-proxy-domain-1.0.0-mule-domain.

For a proxy to leverage the domain, ensure that the domain template is specified in the API proxy pom.xml as a provided dependency.

To configure a domain for the first time:

  1. Obtain a domain artifact in one of the following ways:

    1. Download the API Gateway domain template.

    2. Develop your own custom domain, using the naming convention predefined in the autogenerated proxy:

      • api-proxy-listener-http: The listener configuration for HTTP communications

      • api-proxy-listener-https: The listener configuration for HTTPS communications

  2. Copy the Maven artifact to the domains folder of your running Mule distribution, for example, gateway-proxy-domain-1.0.0-mule-application-template.jar.

  3. Replace mule-application-template with mule-domain, resulting in the string: gateway-proxy-domain-1.0.0-mule-domain.jar.

    Tip: Ensure that the name of the artifact and its Maven coordinates match, for example:

    For Mule 4.2.2 or later to link to generated proxies, the domain file must be named proxy-shared-domain.jar when copied to the domains folder.
  4. Customize the domain template to fit your usage scenario:


Avoiding Port Conflicts

To successfully register an API, you must deploy the API proxy to a Mule instance using a unique endpoint URL. Automatically generated proxies use the path:

To avoid a conflict when running multiple proxies using the same domain, ensure that the proxy paths are unique. Additionally, if you have multiple domains deployed on the same Mule instance, each listener configuration must have a unique port for all domains to be successfully deployed and available to the deployed proxies.

API Gateway Domain Template

If you choose to download and manually configure your API proxy, use the API Gateway domain template.

The API gateway domain template is configured to have a shared HTTP listener configuration ("api-proxy-listener-http") listening on the 8081 port. You can also have a shared HTTPS listener configuration ("api-proxy-listener-https").

To use either configuration, uncomment code from your API gateway domain template and configure your TLS context, such as certificates and passwords. The following list provides the available listeners configurations:

  • api-proxy-listener-http: Used for HTTP communications, binds to all interfaces and uses port 8081 by default.

  • api-proxy-listener-https: Used for HTTPS communications, binds to all interfaces.+

    This domain includes a predefined config.properties file, which enables you to define settings dynamically without having to recompile the domain.

The following example illustrates the properties in the config.properties file:


If you are using Mule 4.2.2 or later with the API gateway domain template 1.0.x, you must modify the domain Java archive (JAR) file for Mule to link with the generated proxies:

  • In META-INF/maven/com.anypoint.mulesoft/gateway-proxy-domain/pom.xml, change the value of groupId to com.mulesoft.anypoint.

  • In META-INF/mule-artifact/classloader-model.json: change the value under "groupId": for com.mulesoft.anypoint.

  • In META-INF/mule-artifact/classloader-model.json, change the value of groupId to com.mulesoft.anypoint.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub
Submit your feedback!
Share your thoughts to help us build the best documentation experience for you!
Take our latest survey!