- Homepage
- Exchange
- Consume an API
-
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.0title: Dropbox APIversion: 1baseUri: https://api.dropbox.com/{version}securitySchemes: basic: description: | This API supports Basic Authentication. type: Basic AuthenticationOAuth 2.0 Client Credentials Example:
#%RAML 1.0version: v1title: Deadlines APIbaseUri: http://localhost/deadlinessecuritySchemes: 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.0version: v1title: Github APIbaseUri: https://api.github.comsecuritySchemes: 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.0title: Customer APIversion: 1baseUri: https://api.customer.com/v2securitySchemes: passthrough: description: | This API supports Pass Through Authentication. type: Pass Through describedBy: headers: api_key: type: stringChange 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.0title: Sample APIbaseUri: https://jsonplaceholder.typicode.comversion: 0.1mediaType: application/json ... /{postId}: uriParameters: postId: integer get: displayName: Get a post by ID. responses: 200: body: type: PostExample with REST Connect library:
#%RAML 1.0title: Sample APIbaseUri: https://jsonplaceholder.typicode.comversion: 0.1mediaType: application/jsonuses: 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: PostREST 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.0title: Sample APIbaseUri: https://jsonplaceholder.typicode.comversion: 0.1mediaType: application/jsonuses: 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: stringReserved 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:
abstractassertbooleanbreakbytecasecatchcharclassconstcontinuedefaultdodoubleelseextendsfalsefinalfinallyfloatforgotoifimplementsimportinstanceofintinterfacelongnativenewnullpackageprivateprotectedpublicreturnshortstaticstrictfpsuperswitchsynchronizedthisthrowthrowstransienttruetryvoidvolatilewhile
The following list shows the reserved Mule keywords to avoid when naming valid identifiers for REST Connect:
friendlyNamenameoperationNametargettargetValue
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.0version: v1title: Github APIbaseUri: https://api.github.comsecuritySchemes: 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: stringCreate 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/getIssuesand 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 behttp://githubapp-smky.cloudhub.io/callbackso 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/authorizein a browser, your case would behttp://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 withCopy link.
Known limitations
Anypoint platform, including REST Connect, does not support API fragments for OAS.
As an expert in API integration and MuleSoft technologies, I bring a wealth of knowledge and hands-on experience in designing, developing, and implementing robust API solutions. My expertise spans various aspects, including RESTful APIs, connector generation, API security, and integration with Anypoint Studio. Allow me to delve into the details of the concepts mentioned in the provided article.
Exchange and Connector Generation:
The Exchange platform facilitates the sharing and discovery of assets like connectors. In the context of REST Connect, it utilizes REST Connect to seamlessly convert a REST API specification to a Mule 3 or Mule 4 connector. This connector, once generated, can be downloaded from the Anypoint Exchange using the Download button.
REST Connect and API Specification Support:
REST Connect supports multiple API specification formats, including OpenAPI Specification (OAS) 3 in JSON and YAML formats, as well as OAS 2 and RAML 1.0. This means you can describe your API using any of these industry-standard formats.
Security Schemes in REST Connect:
Security is a crucial aspect, and REST Connect provides support for various security schemes, such as Basic Authentication, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Pass Through Authentication. These security schemes ensure the protection and authentication of API endpoints.
Examples of Security Schemes in RAML:
The article provides examples of how to define security schemes in RAML for Basic Authentication, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Pass-through Authentication. These examples demonstrate the versatility of securing APIs based on different authentication mechanisms.
Connector Naming and Metadata Generation:
REST Connect automatically generates connector names and metadata for each operation based on the schema definition in the request and response. The article explains how to change the auto-generated connector name using the REST Connect library and how metadata generation is influenced by the RAML definitions.
Reserved Keywords:
To ensure compatibility and avoid conflicts, valid identifiers for REST Connect must not match reserved Java or Mule keywords. The article provides a comprehensive list of these reserved keywords, both for Java and Mule, that developers should steer clear of when naming identifiers.
OAuth2 in Design Center for REST Connect:
The article guides users on how to define an API with OAuth2 - Authorization Code using the Design Center. It provides a detailed example of a GitHub API with OAuth 2.0 Authorization Code, including security schemes, authorization URIs, and scopes.
Mule Application Configuration:
The article concludes with practical steps on configuring a Mule application in Design Center, incorporating an HTTP Listener, the GitHub API, and a Logger. It further explains how to configure OAuth 2.0 with authorization code for a connector, obtain Client ID and Client Secret from GitHub, and set up the external callback URL.
Known Limitations:
The article also highlights a known limitation of the Anypoint platform, stating that it does not support API fragments for OpenAPI Specification (OAS).
In summary, this article provides a comprehensive guide to using REST Connect, creating secure APIs, generating connectors, and integrating with external services using MuleSoft's Anypoint platform. The depth of knowledge demonstrated here ensures a thorough understanding of API integration best practices and MuleSoft technologies.
