Nav

Setting Up and Deploying a Proxy

API Gateway, incorporated in Mule Runtime 3.8 and later, is the server that hosts a Mule proxy application. When you deploy an API in API Manager, you create a proxy application that serves to stop attacks aimed at the actual server. This proxy application is sometimes called an auto-generated proxy.

You can use API Designer, AnyPoint Studio, or Mule runtime to design, run, and debug code prior to deployment of the proxy in API Manager. After deploying an API, you can govern the API using policies. You can set API alerts to send a notification about conditions, such as an API returning a certain HTTP error code.

Deployment Prerequisites

You need to meet the following prerequisites, depending on the type of deployment:

  • General Prerequisites

  • On-premises deployment

    Access to an on-premises Mule 3.8.0 Runtime instance or an API Gateway instance that has been configured to pair with your organization. Configure the on-premises API Gateway if using versions of Mule earlier than 3.8.0.

  • Automatic On-premises deployment

    Valid permissions for both the Runtime Manager and the API Manager of your organization. Also, the on-premises server must be registered.

  • Automatic CloudHub deployment

    Valid permissions for the Runtime Manager and API Manager of your organization.

  • Manual CloudHub deployment

    An Anypoint Platform account and a valid Anypoint Platform client ID and client secret to pair the deployment with an organization.

Setting Up a Proxy

To set up an API proxy to control access to a web service:

  1. Sign in to Anypoint Platform.

  2. Click API Manager.

    The API administration page appears.

    APIadmin

  3. Click the API version, 1.0.development in this example.

    The API Version Details page, which includes the API Status section, appears.

    proxying-your-api-10f00
  4. Click Configure endpoint.

    The Configure endpoint dialog appears.

    walkthrough-proxy-c117a
  5. Accept the default Endpoint with a proxy or select Basic endpoint if you create your API outside API Manager, for example, you created the API using Mule ESB. You don’t need a proxy in this case.

  6. Accept the default Type of endpoint, RAML in this example, or select one of the other type options.

  7. In Implementation URI, accept the default based on the baseUri from the RAML definition, or enter one of the other URI options.

  8. In Proxy settings, select one of the following options:

    • Select the Configure proxy for CloudHub option to deploy to CloudHub. This option fixes the port number to a specific value required by CloudHub.

    • Select the Reference user domain option. This option requires creation of an API Gateway domain.

    • Accept the default (neither option is checked).

  9. In Scheme, accept the default HTTP, or select HTTPS as described in Using HTTPS.

  10. Specify a Port value and a Path, or accept the defaults.

  11. Optionally, customize the response timeout of the auto-generated proxy you are creating for deployment.

    • Expand Advanced Options.

    • In Response Timeout, type a value in milliseconds.

      proxying-your-api-771bd
  12. Click Save & deploy or Save.

About the Type and Implementation URI Options

In the Type field, the following endpoint options are available:

  • HTTP URL

    Choose this option if you built the API using APIkit, and then, enter the address of the HTTP Listener of your deployed APIkit application in Implementation URI. The application can be running on-premises or on CloudHub. For example: http://localhost:8086/api or http://ab-tshirt-orders.cloudhub.io

  • RAML

    Choose this option if you built the API using RAML.

  • WSDL

    Choose this option to manage an existing SOAP API. For the Implemention URI option, enter this address: http://tshirt-service.cloudhub.io/?wsdl

    api-gw-config-ep-wsdl

Deploying a Proxy

You need valid permissions for the Runtime Manager and API Manager of your organization to deploy a proxy.

To CloudHub

In the API Status section of the API version page, click Deploy proxy to deploy the proxy. If you configured the proxy for deployment on CloudHub in the Configure endpoint dialog, then the proxy is deployed in CloudHub.

The status of the API deployment is indicated by the marker in the API Status section of the API version page. While the app is starting, a spinner appears. After the API starts successfully, the light turns green and Re-deploy proxy appears. If you make changes to the configuration, re-deploy the proxy application to the same application on CloudHub.

ReDeployProxy

To a Server On Premises

To manage the API behind this endpoint with SLAs and policies, API Manager needs to register the endpoint with the agent.

  1. In the API Status section of the API version page, click Deploy proxy to deploy the proxy.

    If you did not configure the proxy for deployment in CloudHub in the Configure endpoint dialog, the Deploy proxy dialog appears.

    proxying-your-api-65680
  2. Click Click here.

    Runtime Manager deploys the proxy using the registered Gateway Runtime instance. If there are no registered servers, you are prompted to add one.

    proxying-your-api-b3c5e
  3. Register your server in Runtime Manager by following the instructions in Managing Servers.

To Pivotal Cloud Foundry

This modality is in Beta and only available with the Anypoint Platform Private Cloud Edition. To make this modality available, you must first install and configure the PCF Tile.

Also, the API’s backend application needs to be deployed on the PCF platform before you can run the command that executes the deployment.

Currently, this modality is only available on the command line. To instruct PCF to create and deploy a proxy, you must run the command cf bind-route-service. This command must include the following arguments:

Property Description

Domain name

Domain where you want to host your proxy application

service instance name

Refers to the proxy service, which is different from the service used when deploying Mule applications to PCF. You might have multiple instances of this proxy service, as you’d have one per every organization and environment you own.

-f

(optional) Force command to avoid any message prompts.

--hostname

The host name under which your proxy app is deployed. If nodejs-app.apps.pcf.com is the URL to reach your proxy, then nodejs-app is the hostname and apps.pcf.com is the domain.

-c parameters.json

Reference to a .JSON file that contains more information. Its required structure is explained below.

Your command should look like this:

$ cf bind-route-service apps.pcf.mulesoft.com api_gateway_service --hostname myapp -c input.json

See Deploying to PCF for more details.

Parameters File

One of your properties should be a link to a .JSON parameters file. This file should include the following information:

Parameter Description

orgId

The Anypoint Platform organization in which to deploy the proxy application

envId

The Runtime Manager environment in which to deploy the proxy application

appName

The name with which you want your proxy application to be registered on Runtime Manager. It will also register an API on API Manager under this same name. You will also see the proxy listed under this name if you execute the command cf apps.

--hostname

The host name under which your proxy app is deployed. If nodejs-app.apps.pcf.com is the URL to reach your proxy, then nodejs-app is the hostname and apps.pcf.com is the domain.

'domain`

The domain name where you want to host your application. It should match the domain that you provided as properties on the command.

muleRuntimeVersion

Mule Runtime version with which to run the deployment of the proxy

anypointServiceName

The name of the PCF service that you registered in the Space configuration tool

repFactor

(optional) In case you want your proxy to be deployed on multiple PCF instances.

Your file should hence resemble the following example:


           
        
1
2
3
4
5
6
7
8
9
{
    "orgId": "e2ccc210-95a3-4740-b9cf-1f2d9e693168",
    "envId": "26ad04b9-422c-45f2-8ee0-caeb73e6c9a9",
    "appName": "proxyApp",
    "hostname": "myapp",
    "muleRuntimeVersion": "3.8.1",
   "anypointServiceName": "runtime-manager-service",
    "domain":"apps.pcf.mulesoft.com"
}

To API Gateway 2.x

To deploy a proxy to API Gateway 2.x, follow instructions in the archive documentation.

Downloading a Proxy

You can download the latest or a legacy API Gateway Runtime in ZIP file format. The file is a deployable proxy application.

  1. Click API Status > Download proxy.

    A .zip file is downloaded.

    setting-up-an-api-proxy-7543b
  2. If needed, modify the downloaded zip file to adjust for port conflicts, use shared connector resources, or include custom code for logic that you want to add to the proxy.

  3. Deploy the proxy application.

    After deployment, the yellow circle in the status indicator turns green.

Using HTTPS

When deploying to the CloudHub, you can perform an automatic deployment only if you use an HTTP listener that doesn’t enable HTTPS. If you use HTTPS, add your HTTPS credentials and then perform a manual deployment to CloudHub or deploy on premises.

HTTPS can be applied in the following ways:

  • Between the proxy and the client app (1)

  • Between the proxy and the API (2)

proxyHTTPS-on-two-stages

The way you apply HTTPS and deploy the proxy determines the method you use for setting up the proxy. The following sections describe these methods.

HTTPS with the Client App - On Premises

  1. In the Configure Endpoint menu, select HTTPS as a scheme on the dropdown menu.

  2. The generated proxy has an inbound HTTP Listener connector that references an alternative HTTP Listener Configuration element in a domain, if you use a domain, that uses HTTPS. This configuration element exists in the default Domain file in the API Gateway, but it’s commented out.

    1. In the API Gateway folder, open the file domains/api-gateway/mule-domain-config.xml. It should look like this:

      
                      
                   
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      
      <mule-domain xmlns="http://www.mulesoft.org/schema/mule/ee/domain" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tls="http://www.mulesoft.org/schema/mule/tls" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/ee/domain http://www.mulesoft.org/schema/mule/ee/domain/current/mule-domain-ee.xsd http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd http://www.mulesoft.org/schema/mule/tls http://www.mulesoft.org/schema/mule/tls/current/mule-tls.xsd">
       
         <http:listener-config name="http-lc-0.0.0.0-8081" host="0.0.0.0" port="8081" protocol="HTTP"/>
       
      <!--
          <http:listener-config name="https-lc-0.0.0.0-8082" host="0.0.0.0" port="8082" protocol="HTTPS">
              <tls:context name="tls-context-config">
                  <tls:key-store path="[replace_with_path_to_keystore_file]" password="[replace_with_store_password]" keyPassword="[replace_with_key_password]"/>
              </tls:context>
          </http:listener-config>
      -->
      </mule-domain>
    2. Uncomment the HTTP http:listener-config element named https-lc-0.0.0.0-8082

    3. Fill in the keystore fields in that element with your specific keystore data. Your proxy is ready to deploy.

HTTPS with the Client App - On CloudHub

  1. In the Configure Endpoint dialog, select HTTPS as a scheme on the dropdown menu.

  2. Download the proxy and modify it to include an HTTPS Configuration element with HTTPS credentials. 

  3. Include the following lines of code into your proxy’s proxy.xml file, include this outside any of the flows:

    
                 
              
    1
    2
    3
    4
    5
    6
    
    <http:listener-config name="https-lc-0.0.0.0-8082" host="0.0.0.0" port="8082" protocol="HTTPS">
        <tls:context name="tls-context-config">
           <tls:key-store path="[replace_with_path_to_keystore_file]" password="[replace_with_store_password]"
                 keyPassword="[replace_with_key_password]"/>
        </tls:context>
    </http:listener-config>

    Replace the placeholders with the actual path and passwords of the keystore. 

  4. Verify that the  http:listener element in the flow is correctly referencing this new configuration element you just added.

    config-ref="https-lc-0.0.0.0-8082"

HTTPS with the API

  1. In the Configure Endpoint menu, provide an implementation URI to an HTTPS address. Specifying an HTTPS address modifies the proxy to support HTTPS. By default, the proxy signs requests using the default HTTPS credentials of the JVM.

  2. If you want to include other HTTPS credentials, download the proxy and modify it accordingly.

    If you plan to import your proxy application into Studio 6.x or later, you can choose in API Manager whether to link the application to a domain or not. When importing your proxy application into Studio 5.x, your project is linked to a domain project named api-gateway, which is automatically created in studio if not already present. This domain project is identical to the domain that exists in CloudHub and in your default API Gateway On-Premises. It’s necessary for being able to deploy your app to the Anypoint Studio server under the same conditions as those present when you deploy the app to production. If you modify your domain on the On-Premises installation to include HTTPS credentials, replicate those changes on the domain that exists in Studio to match deployment conditions.

  3. Modify the http:request-config element in the proxy.xml file of the proxy to include TLS configuration elements that point to the required truststore/keystore.

Modifying a Proxy

In most cases, the proxy you generate in API Manager is suitable for deployment out of the box. However, you can modify the proxy to log data to a file or send data to a Splunk account with the Anypoint Splunk Connector, for example. To inspect or change a proxy application, import the proxy application in Anypoint Studio. You can modify the application to perform additional functionality, provided essential structures remain in place. This section shows skeletal XML examples of several types of proxy applications having the essential structures.

To inspect the essential structures of a proxy application:

  1. After setting up a proxy using API Manager, in the Status area, click one of the Download proxy options.

  2. In Studio, select File > Import.

  3. In the Import dialog, expand the Mule node, and select Anypoint Studio Generated Deployable Archive (.zip). Click Next.

  4. Navigate to a proxy zip file that you downloaded from API Manager.

  5. Click Finish.

You can now edit the proxy application.

Handling Domains Linked to the Proxy

After editing the proxy, you can export the project and then deploy it either on-premises or to CloudHub. API Gateway Runtime 1.3 - 2.x has a domain named api-gateway. In Mule 3.8.0, due to the unification of API Gateway Runtime with Mule Runtime 3.8.0 and several usability issues, the api-gateway domain has been removed. If you installed the api-gateway domain and linked the proxy to it, you are exporting and deploying only the proxy app. When deployed to production, the app relies on the domain, if there is one, that exists in that environment.

The following sections introduce the anatomy of the automatically generated proxy applications for a REST API. The anatomy of a SOAP proxy is similar.

Anatomy of a REST Proxy

This section describes the structure of a REST proxy for an API that you can set up in API Manager. From this structure, you can add additional functionality – to log data, for example. 

A proxy abstracts the API to a layer that can be managed by API Manager. A proxy for a REST API should meet the following criteria:

  • Accepts incoming service calls from applications and routes them to the URI of the target API.

  • Copies any message headers from the service call and passes them along to the API.

  • Avoids passing internal Mule headers both to the API and back to the requester. 

  • Captures message headers from the API response and attaches them to the response message.

  • Routes the response to the application that made the service call.

Here’s what a REST proxy might look like in Studio.

proxying-your-api-a2d91

The following example shows an XML configuration of the REST proxy:


    
             
          
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;mule xmlns:http="http://www.mulesoft.org/schema/mule/http"
        xmlns:api-platform-gw="http://www.mulesoft.org/schema/mule/api-platform-gw"
        xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:spring="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/api-platform-gw http://www.mulesoft.org/schema/mule/api-platform-gw/current/mule-api-platform-gw.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd"&gt;
  &lt;api-platform-gw:api id="${api.id}" apiName="${api.name}" version="${api.version}" flowRef="proxy" doc:name="API Autodiscovery"&gt;
        &lt;api-platform-gw:description&gt;${api.description}&lt;/api-platform-gw:description&gt;
    &lt;/api-platform-gw:api&gt;
    &lt;http:request-config name="http-request-config" host="${implementation.host}" port="${implementation.port}" basePath="${implementation.path}" doc:name="HTTP Request Configuration"/&gt;
    &lt;http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/&gt;
    &lt;flow name="proxy"&gt;
        &lt;http:listener config-ref="HTTP_Listener_Configuration" path="${proxy.path}" parseRequest="false" doc:name="HTTP"/&gt;
        &lt;flow-ref name="copy-headers" doc:name="Flow Reference"/&gt;
        &lt;http:request config-ref="http-request-config" method="#[message.inboundProperties['http.method']]"
                      path="#[message.inboundProperties['http.request.path'].substring(message.inboundProperties['http.listener.path'].length()-2)]" parseResponse="false" doc:name="HTTP"&gt;
            &lt;http:request-builder&gt;
                &lt;http:query-params expression="#[message.inboundProperties['http.query.params']]"/&gt;
            &lt;/http:request-builder&gt;
            &lt;http:success-status-code-validator values="0..599" /&gt;
        &lt;/http:request&gt;
        &lt;flow-ref name="copy-headers" doc:name="Flow Reference"/&gt;
    &lt;/flow&gt;
    &lt;sub-flow name="copy-headers"&gt;
        &lt;custom-transformer class="com.mulesoft.gateway.extension.CopyHeadersTransformer" doc:name="Java"/&gt;
        &lt;!-- This can be uncommented for customization
            &lt;copy-properties propertyName="*"/&gt;
            &lt;remove-property propertyName="Host"/&gt;
            &lt;remove-property propertyName="Content-Length"/&gt;
            &lt;remove-property propertyName="MULE_*"/&gt;
            &lt;remove-property propertyName="Connection"/&gt;
            &lt;remove-property propertyName="Transfer-Encoding"/&gt;
            &lt;remove-property propertyName="Server"/&gt;
        --&gt;
    &lt;/sub-flow&gt;
&lt;/mule&gt;

When importing the proxy for the API into Studio 5.x and earlier, the project is linked to a domain project named api-gateway. Studio 5.x and earlier creates a domain project if necessary. The domain project is identical to the domain that exists in CloudHub and in an API Gateway On-Premises by default. Match the production deployment conditions when deploying an app to the Anypoint Studio 5.x server. If you modify the domain on the API Gateway on-prem installation, replicate the changes on the domain that exists in Studio 5.x or earlier. This domain project contains the <http:listener-config statement that the Mule flow requires.

In the API project, configure the property placeholders in the configuration in the mule-app.properties file, which you can find in the Package Explorer under src/main/app.


          
       
1
2
3
4
5
6
7
8
9
api.id=apiId
api.name=My API
api.version=1.0.0
api.description=This is my API
proxy.path=/api/*
implementation.host=www.google.com
implementation.port=80
implementation.path=/
http.port=8081

If an API requires HTTPS communication as shown in the HTTPS example or returns internal API URLs as part of the response, additional configuration might be required.