Using the REST Connect Connector in my Mule4 projects (RAML to Connector)

One out of the box feature available for all engineers when implementing API’s with Mulesoft is the Rest Connect Connector Generator. This is been really useful for me when implementing API’s and one of the main reasons is because in a way it enforces best practices in terms of securing our API’s as well as how we define the data types and samples that the API requires to work correctly.

So the easy way to explain how it works is as simple as say that any RAML definition can transform into an actual connector we can drag and drop in our canvas and be able to use the operations we configured in the RAML as operations including the security from the beginning.

Let’s work a little DEMO

The idea is to show two different common scenarios designing a RAML for an API that will be secured by a OAuth2 policy and a second scenario where we will implement an API that requires the Client credentials in headers for Client ID enforcement policy and adding few features to demonstrate how we can enforce inputs for the connector to work.

First lets go and create our RAML definition for our API secured by OAuth2 , note that the authorizationUri and accessTokenUri are pointing to an existing application I deployed as OAuth provider in Mule.

Now test implement this API in Studio. Simply let’s create a new project and import our RAML so Studio creates the flows and router

Next steps are to deploy our application in Cloudhub and apply the Oauth2 policy from API manager, this way our API will be protected

1. Application deployed in Cloudhub

2. API Active

3. Policy Implemented

Now tryng to confirm if our API fails when no auth is provided

Import our RAML as Connector

Now we are ready to import our API as connector. In order to do it we need to first select Search in Exchange then type the name of your API and Add it.

Now we can see the connector and the operations in out pallette and we are able to drag and drop the connector.

Adding the connector, we are able to create a configuration just like any other in this case our configuration will ask for the required information to connect to our deployed API. Is important to mention that we see client_id and client_secret (I already have created one client using the oauth provider)

So we can use this information in the configuration.

Finally let’s enable wire traffic for HTTP from the Log4j2.xml so we are able to verify OAuth dance happens behind de scene

Now running the request we are able to see our connector is performing the OAuth dance behind the scene and retrieving the information from our API successfully! This means our connector generated by Mulesoft with authentication set is working!

Now let’s add into our API a trait to ask for a X-Request-ID header and our client id and client secret headers for the ClientID Enforcement policy.

our RAML looks like this now:

#%RAML 1.0
title: cool-system-api

traits:
  hastClientCredentials: !include exchange_modules/2f9043cf-a11b-4179-95f9-be3c781af451/client-id-enforcement-trait/1.0.0/client-id-enforcement-trait.raml
  hasrequestId: !include exchange_modules/2f9043cf-a11b-4179-95f9-be3c781af451/request-id-trait/1.0.0/request-id-trait.raml

securitySchemes:
  oauth_2_0:
    description: Mulesoft OAUTH 2
    describedBy:
      headers:
        Authorization: 
          type: string
          required: true
      responses:
        401:
          description: Bad request
        403:
          description: Bad Oauth Request
    type: OAuth 2.0
    settings:
      authorizationUri: http://moran-oauth-provider.us-e2.cloudhub.io/validate
      accessTokenUri: http://moran-oauth-provider.us-e2.cloudhub.io/token
      authorizationGrants: [client_credentials]

/products:
  description: Get product List
  displayName: Get Products
  get:
    securedBy: [oauth_2_0]
    responses:
      200:
        body:
          application/json:
            examples: {"test":"success"}
/user:
  description: Get Users List
  displayName: Get Users
  get:
    is:
      - hasrequestId
      - hastClientCredentials
    securedBy: [oauth_2_0]
    responses:
      200:
        body:
          application/json:
            type: array
  /{userId}:
    description: Get Users List
    displayName: Get Users
    get:
      is:
        - hasrequestId
        - hastClientCredentials
      securedBy: [oauth_2_0]
      queryParameters:
        status:
          type: 
          enum:
            - Active
            - Inactive
      responses:
        200:
          body:
            application/json:
              examples: {"Name":"Edgar"}

Now we can import the latest version of our api from Exchange just as we did at the beggining so now we can see the endpoints we included:

So now if we grab the Get user by userId operation we can see it ask for all required parameters

and one cool feature is that for the ENUM types we see a nice pick list with the unique values we can use to call the API.

Known Limitations

• Anypoint Platform, including REST Connect, does not support API fragments for OAS.
• TLS support can be enabled only for Mule 4 (SmartConnector) connectors. This feature is not supported for Mule 3 (DevKit).

Hope this help you to convert some of the RAML to connectors and give a nicer UI to engineers enforcing best practices.