REST Connect Connector Generator

The Exchange backend uses REST Connect to transparently convert a REST API specification to a Mule 3 and Mule 4 connector. You can use this connector as you would any other in Anypoint Studio.

The Anypoint Exchange Download button lets you download the Mule 3 or Mule 4 Connector.

REST Connect does not currently support custom TLS configurations.

Access Generated Connectors

In Exchange, you can download the Mule 3 or Mule 4 connector from the Download menu:

After deploying a REST asset to Exchange, refresh your screen to ensure that all download options are available.

The Mule 3 connector downloads as a zip file, and the Mule 4 connector downloads as a JAR file.

API Specification Format Support

REST Connect has support for these API specification formats:

OAS 3 - JSON
OAS 3 - YAML
OAS 2 - JSON
OAS 2 - YAML
RAML 1.0

Security Scheme Support

REST Connect supports these security schemes:

Basic Authentication
OAuth 2.0 Client Credentials
OAuth 2.0 Authorization Code
Pass Through
Digest Authentication

If you publish an API specification with another authentication type, you may receive an alert email. To have an auto-generated connector, update your API specification to use one of these supported security schemes.

If the operations defined in your API specification support multiple security schemes, the one that comes first in the list of supported schemes is selected.

Basic Authentication Example:

#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
  basic:
    description: |
      This API supports Basic Authentication.
    type: Basic Authentication

OAuth 2.0 Client Credentials Example:

#%RAML 1.0
version: v1
title: Deadlines API
baseUri: http://localhost/deadlines
securitySchemes:
    oauth_2_0:
        description: Deadlines API supports OAuth 2.0 for authenticating all API requests.
        type: OAuth 2.0
        describedBy:
            headers:
                Authorization:
                    description: Sends a valid OAuth 2 access token.
                    type: string
            responses:
                401:
                    description: Bad or expired token.
                403:
                    description: Bad OAuth request.
        settings:
            accessTokenUri: https://api.example.com/1/oauth2/token
            authorizationGrants: [ client_credentials ]

/deadlines:
    get:
        securedBy: [oauth_2_0]
        displayName: Get deadlines.
        description: Get a list of all registered deadlines.
        responses:
            200:
                body:
                    application/json:
                        example: '[ { "rest-connect": "2017-03-13" } ]'

OAuth 2.0 Authorization Code Example:

#%RAML 1.0
version: v1
title: Github API
baseUri: https://api.github.com

securitySchemes:
  oauth_2_0:
    description: |
      OAuth2 is a protocol that lets external apps request authorization to private details
      in a user's GitHub account without getting their password. This is preferred over
      Basic Authentication because tokens can be limited to specific types of data,
      and can be revoked by users at any time.
    type: OAuth 2.0
    describedBy:
      headers:
        Authorization:
          description: |
            Used to send a valid OAuth 2 access token.

      responses:
        404:
          description: Unauthorized
    settings:
      authorizationUri: https://github.com/login/oauth/authorize
      accessTokenUri: https://github.com/login/oauth/access_token
      authorizationGrants: [ authorization_code ]
      scopes:
        - "user"
        - "user:email"
        - "user:follow"
        - "public_repo"
        - "repo"
        - "repo_deployment"
        - "repo:status"
        - "delete_repo"
        - "notifications"
        - "gist"
        - "read:repo_hook"
        - "write:repo_hook"
        - "admin:repo_hook"
        - "admin:org_hook"
        - "read:org"
        - "write:org"
        - "admin:org"
        - "read:public_key"
        - "write:public_key"
        - "admin:public_key"

Pass-through Example:

#%RAML 1.0
title: Customer API
version: 1
baseUri: https://api.customer.com/v2
securitySchemes:
  passthrough:
    description: |
      This API supports Pass Through Authentication.
    type: Pass Through
    describedBy:
      headers:
        api_key:
          type: string

Change an Auto-Generated Connector Name

REST Connect generates the names of operations based on operationName, displayName, and endpoint in that order. To modify a generated name, you can point to the REST Connect library and use the operationName annotation from a method such as GET, POST, and DELETE, or you can change the text in displayName under the method.

Example with displayName:

#%RAML 1.0
title: Sample API
baseUri: https://jsonplaceholder.typicode.com
version: 0.1
mediaType: application/json

  ...
  /{postId}:
    uriParameters:
      postId: integer

    get:
      displayName: Get a post by ID.
      responses:
        200:
          body:
            type: Post

Example with REST Connect library:

#%RAML 1.0
title: Sample API
baseUri: https://jsonplaceholder.typicode.com
version: 0.1
mediaType: application/json

uses:
  rest-connect: exchange_modules/org.mule.connectivity/rest-connect-library/1.0.0/rest-connect-library.raml

  ...
  /{postId}:
    uriParameters:
      postId: integer

    get:
      (rest-connect.operationName): Retrieve a post by id
      displayName: Get a post by ID.
      responses:
        200:
          body:
            type: Post

Metadata Limitations

REST Connect generates metadata for each operation based on your schema definition in the request and response for each method in your RAML. REST Connect cannot generate metadata based on examples in the RAML.

Because only one input/output type is supported for each operation, REST Connect selects the first one that was declared. You can change this behavior by using the 'default' property from the REST Connect library.

Example with REST Connect library:

#%RAML 1.0
title: Sample API
baseUri: https://jsonplaceholder.typicode.com
version: 0.1
mediaType: application/json

uses:
  rest-connect: exchange_modules/org.mule.connectivity/rest-connect-library/1.0.0/rest-connect-library.raml

  ...
  /{postId}:
    uriParameters:
      postId: integer

    get:
      displayName: Get a post by ID.
      responses:
        200:
          body:
            application/json:
             type: string
            application/xml:
             (rest-connect.default): //this sets application/xml response by default
             type: string

Reserved Keywords

Valid identifiers for REST Connect must not match any of the reserved Java keywords or reserved Mule keywords.

The following list shows the reserved Java keywords to avoid when naming valid identifiers for REST Connect:

abstract
assert
boolean
break
byte
case
catch
char
class
const
continue
default
do
double
else
extends
false
final
finally
float
for
goto
if
implements
import
instanceof
int
interface
long
native
new
null
package
private
protected
public
return
short
static
strictfp
super
switch
synchronized
this
throw
throws
transient
true
try
void
volatile
while

The following list shows the reserved Mule keywords to avoid when naming valid identifiers for REST Connect:

friendlyName
name
operationName
target
targetValue

OAuth2 in Design Center for REST Connect

Define an API with OAuth2 - Authorization Code and one operation in Design Center. You can use the following GitHub API example:

#%RAML 1.0
version: v1
title: Github API
baseUri: https://api.github.com

securitySchemes:
 oauth_2_0:
   description: |
     OAuth2 is a protocol that lets external apps request authorization to private details
     in a user's GitHub account without getting their password. This is preferred over
     Basic Authentication because tokens can be limited to specific types of data,
     and can be revoked by users at any time.
   type: OAuth 2.0
   describedBy:
     headers:
       Authorization:
         description: |
           Used to send a valid OAuth 2 access token.
     responses:
       404:
         description: Unauthorized
   settings:
     authorizationUri: https://github.com/login/oauth/authorize
     accessTokenUri: https://github.com/login/oauth/access_token
     authorizationGrants: [ authorization_code ]
     scopes:
       - "user"
       - "user:email"
       - "user:follow"
       - "public_repo"
       - "repo"
       - "repo_deployment"
       - "repo:status"
       - "delete_repo"
       - "notifications"
       - "gist"
       - "read:repo_hook"
       - "write:repo_hook"
       - "admin:repo_hook"
       - "admin:org_hook"
       - "read:org"
       - "write:org"
       - "admin:org"
       - "read:public_key"
       - "write:public_key"
       - "admin:public_key"

/search:
 /issues:
   get:
     displayName: Get Issues
     queryParameters:
       q:
         displayName: Query
         description: |
           The search terms.
         type: string
         required: true
       sort:
         displayName: Sort
         description: |
           The sort field. Can be comments, created, or updated. Default: results are sorted by best match.
         type: string
         required: false
       order:
         displayName: Order
         description: |
           The sort order if a sort parameter is provided. One of asc or desc. Default: desc
         type: string
         required: false
     responses:
       200:
         description: |
           Successful call
         body:
           application/json:
             type: string

Create a new API specification project named Github API in Design Center, and copy and paste the example above. From the API Designer, click Publish to Exchange:
Create a simple Mule application in Design Center of an HTTP Listener, the Github API, and a Logger. This app listens to https://my-app.cloudhub.io/getIssues and returns the results based on your search term.
Configure OAuth 2.0 with authorization code for a connector. Most of the fields are auto-populate based in the GitHub API specification.
Get the Client ID and Client Secret for your GitHub Account. You can find your Client ID and Client Secret if you go to Settings > Developer settings in GitHub. If you don’t have an OAuth App in GitHub, you can create one with the New OAuth App.
Because GitHub API’s base URL is api.github.com, you can put “/” in the Base Path.
Match and modify your external callback URL. The callback URL receives an access token from GitHub. By default, the connector shows http://my-app.cloudhub.io/callback, but you need to modify it specific to your app. The demo app’s callback URL should be http://githubapp-smky.cloudhub.io/callback so I need to replace “my-app” with “githubapp-smky.” You can find this information to go to the menu and select the copy link in Design Center.
After you get your external callback URL, specify the same URL in your GitHub settings.
You are ready to retrieve an access token from GitHub. In this case, go to http://githubapp-smky.cloudhub.io/authorize in a browser, your case would be http://my-app.cloudhub.io/authorize - replace my-app.cloudhub.io with the one you get with Copy link. When you reach this URL, your browser asks you to log into GitHub.
When your access token is issued properly, you can get issues related to Salesforce from GitHub by using http://my-app.cloudhub.io/getIssues - my-app.cloudhub.io should be replaced with the one you get with Copy link.