Connecting Mule API Gateway and ESB in Hybrid Mode

** To view “hello-world.raml”, please go to the very bottom of this post.
APIs are driving the digital economy. One of the key players in the API field is MuleSoft. Instead of a labyrinth of overlapping products offerings, MuleSoft provides the Anypoint Platform with Mule API gateway and a nimble Mule ESB that can run in the cloud, on-prem or in hybrid mode. Mule promotes a wholesome API approach called API-led Connectivity.

3-9-2017 update: with Mule 3.8.x, please see this updated post for new instructions.

In this post, I will demonstrate an end to end example on how to connect the front-end Mule API gateway to the back-end Mule ESB server in hybrid mode. I’ll also show how easy it is to apply various policies to the API proxy. The final section illustrates applying LDAP security policy to the API interface.

This post assumes you have the basic working knowledge of Anypoint Studio.

Mule API Gateway Server and ESB Server Installation and Configuration

If you don’t have an Anypoint Platform account, you can create one for free at http://anypoint.mulesoft.com.

• Download and install the trial version of Mule API gateway from here: https://www.mulesoft.com/ty/dl/api-gateway. The current version is “api-gateway-distribution-standalone-2.2.0.zip”.
• Download and install the trial version of Mule ESB from here: https://www.mulesoft.com/ty/dl/mule. The current version is “mule-ee-distribution-standalone-3.7.3.tar.gz”.

After the servers are installed and running, we can move on to register these local servers in the “cloud”.

Register the Servers

From the Anypoint Platform web console, click on “servers”, and copy the “amc_setup” line as shown below (your console will have a different amc_setup string):

From the command prompt, cd to the bin directories of the servers, and execute the amc_setup commands.

My local AGI Gateway server bin directory is C:\mule\api-gateway-standalone-2.2.0\bin

Run “amc_setup -H 92fae9e9-84eb-44dd-b1c4-dab45d969be0—1xxxx local-gw”

Do the same for ESB server in C:\mule\download\mule-enterprise-standalone-3.7.3\bin

“amc_setup -H 92fae9e9-84eb-44dd-b1c4-dab45d969be0—1xxxx local-esb”

Now, our local servers will show up in the AMC (Anypoint Management Console):

Part I – Create RAML and the Application

Now the servers are configured and running. Let’s create the API application.

1. Create the RAML with the Mule API management console

Technically you can use any editor to create the RAML.  In this case, we will create the RAML from Mule API management console. Login to anypoint.mulesoft.com; click on “API”, then click “Add new API”, type in the API name “hello”, and start to edit/design the RAML.

In this example, my finished RAML is the good O “Hello world” (see the very end of this post)

Please note this post doesn’t cover the steps of editing the RAML. You can find plenty of examples online on RAML.

2. Create the API project in Sutdio

After you are done editing the RAML, download it and use Anypoint Studio to create the API project based on the RAML

3. Finish Implementing the application

With the Studio, you can implement complicated functions based on RAML. In this example, I only touched the JSON response with something like “This is local get impl — hello #[name]”.

4. Deploy the application to ESB

Export the finished project as a .zip file. Then login to anypoint.mulesoft.com, click on CloudHub, then “Applications/Deploy application”, select application name, select “local-esb” as target (Make sure the server is running, otherwise, it will not show up in the dropdown list)

Check your application configuration file, and take a note of the URL (host, port, path) of your application. In this example, it is http://localhost:8082/api/*

Please note:

• I’m using localhost in this example, if you want to access the service or the API interface directly from the internet, the server needs to be on a domain that’s publicly accessible.
• Do not bypass the AMC console to deploy the application directly to the local server (such as copying the zip file to the apps directory). If you do, it won’t be visible from CloudHub console!
• You can also deploy the application to CloudHub; then your URL will be something like http://myapp-name.cloudhub.io. I use “local-esb” in this case to show you the hybrid deployment.

5. Kick the tires

Browse to http://localhost:8082/api/console/. You can test the API using the console. You can also hit it directly with Chrome (IE may not like the JSON response) http://localhost:8082/api/hello/foo, you should see something like:

  {  “greeting”: “This is local get impl — hello foo”  }

Now we know the application is running on an ESB server. In the next section we will expose this service through the API Gateway.

Part II – Deploy the API proxy

1. In step 1 of the last section, we merely used the API management console to create the RAML file. We haven’t done anything to manage the “hello” API.

Let’s go back to the API management console, click the version number 1 to the right of API “hello”.

On the next screen, click on “configure endpoint”:

2. Select the configuration values:

Remember the application runs on ESB with the endpoint “http://localhost:8082/api”

3. Deploy the API proxy

Click Save & Deploy, then select Gateway “local-gw”, and deploy the proxy

Please note since the ESB is running on localhost, I have to deploy the API proxy on the localhost. If the ESB is running on a publically accessible domain, then you can deploy the API proxy either in cloud or on-prem, as long as the gateway server can access the ESB server.

I have picked proxy to run on 8081 and path is /api-proxy

When the deployment is complete, you will see a “hello-v2-2.x.x” (something like that, it’s a system generated default proxy file name) is deployed in the apps folder on the local Gateway server. If you ever wondered where is the “api/console” link for the proxy, in this default generated project, the console path is actually “http://localhost:8081/api-proxy-console”.

4.  Test the proxy

With Chrome, hit the proxy endpoint http://localhost:8081/api-proxy/hello/bar, you should see similar response like step 5 in the previous section

{ “greeting”: “This is local get impl — hello bar” }

5. Let’s sum it up:

• We have created a “hello world” RAML using the RAML designer from the API management console.
• We have created an application based on the RAML using Anypoint Studio.
• We have deployed the application to the ESB server: “local-esb”.
• We have created a proxy for API “hello” and deployed the proxy to the Gateway server: “local-gw”. The proxy is wired to the “hello” application on the ESB.

Part III – Manage the API

So far the proxy is a mere pass-through. Let’s do something with it.

Click “Policies” tab on the lower part of the screen. Let’s test with a simple “Rate Limiting” policy. Let’s set 3 requests per minute.

Once the policy is applied, try to hit these two endpoints consecutively, and observe the responses.

• API-proxy endpoint http://localhost:8081/api-proxy/hello/foo
• Application endpoint http://localhost:8082/api/hello/bar

You will see the API-proxy endpoint limits to 3 calls per minutes; whereas, the application endpoint has unlimited calls. That’s how/why you use API gateway to control the access to backend service. In this case, it’s a service running on an ESB server. In the real world, this service may be running behind some firewall and access is only allowed via the API gateway.

You can also apply the HTTP basic authentication policy. Remember to enable “Simple Security Manager” before “HTTP basic authentication”. The simple security manager is a fake one. It asks you to set a fake user and password. When you enable HTTP basic authentication, it will use that fake credential to validate your request.

Part III – Testing LDAP Security Manager

To test the LDAP security policy requires a lot more work. Please follow these steps:

• Download and install open LDAP: http://www.userbooster.de/en/download/openldap-for-windows.aspx
• LDAP basic configuration: http://kukusan-network.blogspot.com/2012/01/how-to-setting-ldap-openldap-in-windows.html
• To explore the LDAP sever, download LDAP explorer tool from here: http://ldaptool.sourceforge.net/

Assume you followed the above steps to install and configure the open LDAP, whey you apply the “LDAP security manager” policy, set the parameters as shown on the following screen:

After you apply the policy, you will see only these two users can access the API-proxy

“fsatrio/SomePassword” and “ppratomo/SomePassword”.

Ldap configure notes:

ldapmodify.exe -a -x -h localhost -p 389 -D “cn=manager,dc=maxcrc,dc=com” -f C:\OpenLDAP\ldifdata\step1.ldif -w secret

How To Fix Gssapi64.dll is Missing – Not Found Error

set path=%path%;C:\Program Files\MIT\Kerberos\bin

ldapmodify.exe -a -x -h localhost -p 389 -D “cn=manager,dc=maxcrc,dc=com” -f c:\OpenLDAP\ldifdata\samz.ldif -w secret

LDAP URL – ldap://localhost:389/ou=employees,dc=company,dc=org

ldap://localhost:389/ou=People,dc=maxcrc,dc=com

***********

Status      Applied

Description

Injects an LDAP-based security manager into its target API. Organizations often use LDAP as a central repository for user information and as an authentication API.

LDAP server URL
ldap://localhost:389/
LDAP user DN
cn=Manager,dc=maxcrc,dc=com
password: secret
LDAP search base
ou=people,dc=maxcrc,dc=com
LDAP search filter
(uid={0})

**************

Hello world RAML

#%RAML 0.8
title: hello-world RAML by Yuan Meng
version: v1
securitySchemes: 
  - basic:
      type: Basic Authentication
baseUri: http://localhost:8082/api/{version}
mediaType: text/json
/hello:
  post:
      description: add names, and greeting words
      securedBy: [basic]
      body:
        application/json:
          example: |
            {
              "name" : "jack",
              "greeting" : "hello"
            }
      responses:
        200:
          body:
            application/json:
              example: |
                {
                [
                  "name": "jack",
                  "greeting": "hello"
                ]
                }
  /{name}:
    get:
      description: say hello to {name}
      securedBy: [basic]
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "greeting": "hello jack"            
                }