Nav

About Converting a RAML to a Connector Using REST Connect

REST Connect quickly converts a RAML 1.0 API specification to a connector, which you can use in a Mule application in the Design Center feature of Anypoint Platform and in Anypoint Studio.

RAML Specification Support

REST Connect supports RAML v1.0. If you publish a RAML v0.8 API Specification, you may receive an alert email. To have an auto-generated connector, convert your API specification to RAML v1.0.

Security Scheme Support

REST Connect supports the following 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 recieve an alert email. To have an auto-generated connector, update your API specification to use one of the supported security schemes mentioned above.

Basic Authentication Example:


         
      
1
2
3
4
5
6
7
8
9
#%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:


         
      
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
#%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:


         
      
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
42
43
44
45
46
47
#%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"

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:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#%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.1.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

OAS Support

REST Connect supports RAML v1.0 and supports OAS through the OAS conversion feature in Exchange 2. Exchange lets you directly add an OAS file in the Exchange user interface. Exchange converts the OAS file to a RAML, and REST Connect generates a connector based on the RAML.

You can also add an OAS file through API Designer in Design Center. API Designer converts the OAS file to a RAML and allows you to publish the RAML to Exchange. Once the RAML is published in Exchange, REST Connect generates a connector based on the RAML.

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.

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:

    
                
             
    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
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    
    #%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:

    Publish to Exchange icon in API Designer

  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.

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

    API Configuration screen

  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.

    Ready to Deploy menu

  8. After you get your external callback URL, specify the same URL in your GitHub settings.

    Authorization Callback URL field

  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.