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.

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.

Usage

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="0.0.0.0" port="8081" protocol="HTTP"/>
</http:listener-config>xml

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">
...xml

Configure the Domain Used by an API Proxy

Configure the domain used by an API proxy by completing the following steps:

Navigate to Anypoint Platform > API Manager.
In API Administration, click Add API and select Add new API.
Select Mule Gateway as your runtime.
Select Deploy a proxy application for Proxy type.
Select Hybrid for Target Type, then select the target server.
Click Next.
Select an API from the following options:
- Click Select API from Exchange if you have an API shared with you through Exchange that you want to manage.
  1. Click the API from the list under Select API. You can search for a specific API if needed.
  2. Update the Asset type, API version, and Asset version if you are not using the latest version.
    
    For more information about versions in Exchange, see Asset Versions.
  3. If you chose a RAML/OAS asset type, view the Conformance Status of the API to ensure the API is conformant. If the Conformance Status is nonconformant, after deployment, view the Governance Report to find and fix the conformance issues. For more information about the Governance Report, see Governing API Instances.
- Click Create new API:
  1. Enter a Name for the new API asset.
  2. Select the Asset type from the following options:
    
    REST API: Select this option if you have a RAML or OAS API definition file you want to include for your asset.
    
    Upload either a RAML or OAS file for your REST API. Versions 2.0.0 and later are the recommended versions for OAS or RAML specs, because these versions add native OAS support. If you upload an OAS API specification to an API proxy version 1.0 or earlier, your API specification is translated to RAML.
    
    HTTP API: Select this option if you do not have an API definition file you want to include for your asset.
    
    SOAP API: Select this option if you have a WSDL API definition file or an external link to the file.
    
    Upload a WSDL file for your SOAP API or add the link to the file.
    This option is not available for Flex Gateway runtime at this time.
  3. Update the Asset type, API version, and Asset version if you are not using the latest version.
    
    For more information about versions in Exchange, see Asset Versions.
  4. If you chose a RAML/OAS asset type, view the Conformance Status of the API to ensure the API is conformant. If the Conformance Status is nonconformant, after deployment, view the Governance Report to find and fix the conformance issues. For more information about the Governance Report, see Governing API Instances.
Click Next.

Configure the downstream configuration settings:

Expand for configuration settings.

Field Name Description Required Notes

Field Name	Description	Required	Notes
Protocol	Specifies whether to use HTTP or HTTPS for the validations.	Yes	If you select HTTPS, specify a TLS context for inbound traffic.
Inbound TLS	Specifies the TLS context to secure inbound traffic.	No	Only available on Mule 4+. If you can’t see a context, ensure that you have the correct permissions. To enable HTTPS in Mule 3 environment, see enable HTTPS in Mule 3x.
Port	Specifies the number to use if the displayed port is incorrect.	Yes
Base path	Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash `/`.	Yes
Instance label	Specifies a label for the API.	No	If you have multiple managed instances of the same API, add a label to differentiate each instance from the others.
Advanced Options
Consumer endpoint	Specifies a proxy application’s address for consumers to use for sending requests.	No
Client provider	Specifies a client provider for the API.	Yes	Anypoint Platform acts as the client provider by default. To configure an external client provider, see Client Providers.
Request timeout	Specifies the duration after which a request times out.	No
Proxy Version	Specifies the version of the proxy to use for the endpoint.	No
Service Name	Name of your WSDL service.	Yes	Only avaliable for WSDL APIs.
Service Port	Port for your WSDL your service.	Yes	Only avaliable for WSDL APIs.
Service Namespace	Namespace of your WSDL service.	Yes	Only avaliable for WSDL APIs.
Enable Console	Specifies whether you can expose and test your API specification.	No	You can specify a different path in Console Path, for example, `/spec/*`. Only available if you have an attached API definition. Only available on Mule 3+.
Validations	Specifies whether to validate inbound requests against a provided specification.	No	Only available if you have an attached API definition. Only available on Mule 3+.
Strict validations (optional)	Specifies whether to validate inbound requests against query parameters.	No	Only available if you have an attached API definition. Only available on Mule 3+
User Domain	Specifies whether to use an API gateway domain.	No	If you chose Hybrid as the proxy deployment target previously in the configuration, ensure that you select this option. You must install the API gateway domain in Mule 3.8 and later.

Protocol

Specifies whether to use HTTP or HTTPS for the validations.

Yes

If you select HTTPS, specify a TLS context for inbound traffic.

Inbound TLS

Specifies the TLS context to secure inbound traffic.

Only available on Mule 4+. If you can’t see a context, ensure that you have the correct permissions. To enable HTTPS in Mule 3 environment, see enable HTTPS in Mule 3x.

Port

Specifies the number to use if the displayed port is incorrect.

Yes

Base path

Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash /.

Yes

Instance label

Specifies a label for the API.

If you have multiple managed instances of the same API, add a label to differentiate each instance from the others.

Advanced Options

Consumer endpoint

Specifies a proxy application’s address for consumers to use for sending requests.

Client provider

Specifies a client provider for the API.

Yes

Anypoint Platform acts as the client provider by default. To configure an external client provider, see Client Providers.

Request timeout

Specifies the duration after which a request times out.

Proxy Version

Specifies the version of the proxy to use for the endpoint.

Service Name

Name of your WSDL service.

Yes

Only avaliable for WSDL APIs.

Service Port

Port for your WSDL your service.

Yes

Only avaliable for WSDL APIs.

Service Namespace

Namespace of your WSDL service.

Yes

Only avaliable for WSDL APIs.

Enable Console

Specifies whether you can expose and test your API specification.

You can specify a different path in Console Path, for example, /spec/*. Only available if you have an attached API definition. Only available on Mule 3+.

Validations

Specifies whether to validate inbound requests against a provided specification.

Only available if you have an attached API definition. Only available on Mule 3+.

Strict validations (optional)

Specifies whether to validate inbound requests against query parameters.

Only available if you have an attached API definition. Only available on Mule 3+

User Domain

Specifies whether to use an API gateway domain.

If you chose Hybrid as the proxy deployment target previously in the configuration, ensure that you select this option. You must install the API gateway domain in Mule 3.8 and later.

Click Next.

Configure the upstream configuration settings:

Expand for configuration settings.

Field Name	Description	Required	Notes
Upstream URL	The URL to access for the proxy or the API.	Yes	For example, you can use the URL of your API asset in Exchange.
Outbound TLS	Specifies the TLS context to secure outbound traffic.	No	Only available on Mule 4+. If you can’t see a context, ensure that you have the correct permissions.

Field Name

Description

Required

Notes

Upstream URL

The URL to access for the proxy or the API.

Yes

For example, you can use the URL of your API asset in Exchange.

Outbound TLS

Specifies the TLS context to secure outbound traffic.

Only available on Mule 4+. If you can’t see a context, ensure that you have the correct permissions.

Click Next.
Review your selections and edit them if necessary.
If you are ready to deploy, click Save & Deploy. Otherwise, you can select Save, to save the API instance and deploy it at a later time.
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:

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
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.
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:
```
<groupId>com.mulesoft.anypoint</groupId>
<artifactId>gateway-proxy-domain</artifactId>
<version>1.0.0</version>
<packaging>mule-domain</packaging>xml
```
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.
Customize the domain template to fit your usage scenario:

<dependency>
    <groupId>com.mulesoft.anypoint</groupId>
    <artifactId>gateway-proxy-domain</artifactId>
    <version>1.0.0</version>
    <classifier>mule-domain</classifier>
    <scope>provided</scope>
</dependency>

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: http://0.0.0.0:8081.

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 Leaving the Site 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:

proxy.port=8081
implementation.protocol=HTTP
inbound.keystore.path=path
inbound.keystore.keyPassword=changeit
inbound.keystore.password=changeit
inbound.keystore.algorithm=
inbound.keystore.type=JKS
inbound.keystore.alias=aliasProperties

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.

Domain Support for Mule 4 API Proxies

API Proxies and Domains Overview

Usage

Configure the Domain Used by an API Proxy

Configuring a Domain for the First Time

Avoiding Port Conflicts

API Gateway Domain Template

See Also