#%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
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:
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 behttp://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 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
.