Contact Us 1-800-596-4880

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

  1. 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
  2. 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:

    rest connect publish to exchange
  3. 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.

    rest connect dc flow
  4. Configure OAuth 2.0 with authorization code for a connector. Most of the fields are auto-populate based in the GitHub API specification.

    rest connect api config
  5. 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.

  6. Because GitHub API’s base URL is api.github.com, you can put “/” in the Base Path.

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

    rest connect ready to deploy
  8. After you get your external callback URL, specify the same URL in your GitHub settings.

    rest connect auth callback url
  9. 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.

  10. 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.

Known limitations

  • Anypoint platform, including REST Connect, does not support API fragments for OAS.