REST Connect Connector Generator | MuleSoft Documentation
# REST Connect Connector Generator
The Exchange backend uses REST Connect to transparently convert a REST API specification to a Mule 4 connector. You can use this connector as you would any other in Anypoint Studio.
## Access Generated Connectors
In Exchange, download the generated connector from the **Download** menu.
After deploying a REST asset to Exchange, refresh your screen to ensure that all download options are available.   
---  
Mule 4 connectors download as JAR files.
## API Specification Format Support
REST Connect supports 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 an unsupported authentication type, you receive an alert email. If this happens, update your API specification to use one of the 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 used.
### 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’s Name
REST Connect generates the names of operations based on the `operationName`, `displayName`, and `endpoint` attributes, in that order.
To modify a generated connector name, change the text in `displayName`, for example:
```
#%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
```

You can also modify a generated connector name by pointing to the REST Connect library and using the `operationName` annotation from a method such as GET, POST, and DELETE, for example:
```
#%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.
REST Connect supports only one input/output type and uses the first one declared in the API specification. You can change this behavior by using the `default` property from the REST Connect library.
The following example uses the 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 use any reserved Java or Mule keywords.
The following list shows the reserved Java keywords to avoid when naming valid identifiers for REST Connect:
  * `abstract`
  * `boolean`
  * `continue`
  * `default`
  * `extends`
  * `finally`
  * `implements`
  * `instanceof`
  * `interface`
  * `package`
  * `private`
  * `protected`
  * `strictfp`
  * `synchronized`
  * `transient`
  * `volatile`


The following list shows the reserved Mule keywords to avoid when naming valid identifiers for REST Connect:
  * `friendlyName`
  * `operationName`
  * `targetValue`


## Generating Connectors With TLS Support
Mule 4 (SmartConnector) connectors support Transport Layer Security (TLS).
When you enable TLS support and generate a connector:
  * The connector is upgraded to run on Mule runtime 4.6.
  * TLS is enabled, so that Anypoint Studio displays a form for collecting the connector’s required TLS connection configuration information. To see the connection configuration properties, select **Edit inline** or **Global reference** from the **Tls context** field.


To enable TLS, add a `properties.json` file to the root directory of the Design Center API project for your app:
  1. In Design Center, Select **Files +** > **New file**.
  2. In the **Add new file** window, select **API format > other**, name the file `properties.json`, and then click **Create**.
  3. In the new file, add `"tlsEnabled": true`.
Add the `properties.json` file only if you want to enable TLS support or explicitly opt out of it. If you don’t add a `properties.json` file to your API project, the REST Connect Service generates the standard connector artifacts without TLS support.   
---
The following list shows the reserved Mule keywords to avoid when naming valid identifiers for REST Connect:
  * `friendlyName`
  * `operationName`
  * `targetValue`


## Generating Connectors With TLS Support
Mule 4 (SmartConnector) connectors support Transport Layer Security (TLS).
When you enable TLS support and generate a connector:
  * The connector is upgraded to run on Mule runtime 4.6.
  * TLS is enabled, so that Anypoint Studio displays a form for collecting the connector’s required TLS connection configuration information. To see the connection configuration properties, select **Edit inline** or **Global reference** from the **Tls context** field.


To enable TLS, add a `properties.json` file to the root directory of the Design Center API project for your app:
  1. In Design Center, Select **Files +** > **New file**.
  2. In the **Add new file** window, select **API format > other**, name the file `properties.json`, and then click **Create**.
  3. In the new file, add `"tlsEnabled": true`.
Add the `properties.json` file only if you want to enable TLS support or explicitly opt out of it. If you don’t add a `properties.json` file to your API project, the REST Connect Service generates the standard connector artifacts without TLS support.   
---  


After you add the `properties.json` file and enable TLS, Anypoint Studio displays the TLS configuration form for the connector.
When you add a `properties.json` file to your project, ensure that the `tlsEnabled` property is set correctly with a valid boolean value of either `true` to enable TLS or `false` to explicitly disable TLS. If the `properties.json` file is invalid or the property is incorrectly set, the connector generation is aborted.
## View Mule Runtime Version and Compatible Java Version
To view the minimum Mule runtime version or the compatible Java versions for the patch versions of a connector:
  1. From Exchange, select a connector.
  2. In the asset details page, click **View versions**.


## Upgrading a REST Connect Generated Connector
To update your REST-Connect-generated connector to use the latest version of Mule runtime and to be compatible with Java 17:
  1. In Design Center, open your API project.
  2. Click **Publish**.
The connector is regenerated.


If you want to add TLS support to your application, add it before re-generating the connector so that you only have to test your app once.
## Known Limitations
  * Anypoint Platform, including REST Connect, does not support API fragments for OAS.
  * Chinese characters are not supported in API specs or their dependencies. Japanese characters are supported in the `description` and `example` tags.