# Setting Up The OpenAPI Connector
In this guide, we'll walk you through installing and setting up an OpenAPI connector in your Workato account.
Refer to the Using OpenAPI connector to create custom connectors guide if you want to fully customize your connector.
To set up an OpenAPI connection, you'll need:
Privileges in Workato that allow you to create connections.
A Swagger file that:
- Conforms to OpenAPI v2 or v3 specifications (opens new window)
- Is valid JSON or YAML
# Step 1: Install The Connector
The first step is to install the connector in your Workato account:
Click Install connector.
Click Release latest version.
# Step 2: Configure The Connection In Workato
- Step 2.1: Provide The OpenAPI Document
- Step 2.2: Define The Authentication Settings
- Step 2.3: Define Server And Testing URLs
- Step 2.4: Customize The Interface
# Step 2.1: Provide The OpenAPI Document
In this step, you'll provide the Swagger file containing the API definition.
How you accomplish this is dependent on whether the file is publicly accessible on the internet:
My file is publicly accessible
If the Swagger file is publicly accessible:
Select Document URL as the OpenAPI document source.
In the Document URL field, paste the document URL to the file.
Note: Files are only downloaded and parsed at recipe design time. When recipes are run - or when OpenAPI actions are executed - the file won't be downloaded.
My file is not publicly accessible
If the Swagger file isn't hosted or isn't publicly accessible, you can copy and paste the file into Workato:
Select Download content as the OpenAPI document source.
In the Document content field, paste the contents of the file.
# Step 2.2: Define The Authentication Settings
Next, you'll define the authentication method for the connection. Learn more about the supported authentication methods in the OpenAPI overview guide.
Select the method you're using from the Authentication Method menu.
# Step 2.3: Define Server And Testing URLs
Next, you'll define the server and testing URLs for the connector:
Server URL: Enter the URL to the application's target host or service, including the
https://. This is the base URL for requests sent by the connector. For example:
Relative endpoint paths from the API definition will be appended to this URL to construct the full endpoint URL.
Test Request URL: Enter the relative path of an API endpoint that Workato can use to verify the connection. This path will be appended to the Server URL to construct a full endpoint URL for testing. For example:
Connections are successful when the API responds with a
For example: A Server URL of
https://api.example.com and a Test Request URL of
/users/profile creates a full request URL of:
# Step 2.4: Customize The Interface
The OpenAPI connector automatically generates the user interface based on the content of the provided Swagger file. The following elements can be customized to improve the user experience:
- Object names
- Object hints
- Field names
- Field hints
- Links to external documentation
- API operation grouping
- Fields to ignore
Check out the Customizing OpenAPI user interfaces guide for more info and examples.
# Step 3: Test The Connection
When finished configuring the connection, click Connect to save and test the connection.
Last updated: 11/28/2022, 11:53:55 AM