OpenAPI
Learn how to use the OpenAPI Connector in DBSync Cloud Workflow
Overview
The OpenAPI Connector in DBSync Cloud Workflow enables integration with any REST-based API that follows the OpenAPI (Swagger) specification. This connector allows organizations to connect custom applications, internal services, or third-party platforms that do not have a pre-built DBSync connector.
By leveraging an OpenAPI definition, DBSync automatically understands available endpoints, request parameters, and response structures - making it possible to build workflows without writing custom code.
What is a Swagger File?
A Swagger file is a JSON or YAML document that adheres to the OpenAPI Specification. It includes all the necessary details to describe an API, such as paths, operations, parameters, data types, and security schemes. This file can be imported into DBSync to automatically generate API operations.
Capabilities
DBSync's Open API Connector enables users to integrate with any REST API defined using OpenAPI (Swagger). Once configured, it dynamically generates operations such as GET, POST, PUT, DELETE, PATCH, and HEAD based on the imported specification. Users can then utilize these operations in their workflows to automate data movement and interactions across systems.
Key Benefits
For Business Users:
Universal Integration: Connect virtually any modern SaaS or internal system.
Faster Time to Value: Avoid custom development and reduce integration timelines.
Future-Proof Architecture: Integrate new APIs as business systems evolve.
For Technical Teams:
Standards-Based Integration: Built on the OpenAPI (Swagger) specification.
Flexible Authentication Models: Supports multiple auth methods.
Dynamic Object Discovery: Endpoints and schemas are auto-discovered from the API spec.
Supported Features
Connects to any REST API with a valid OpenAPI (Swagger) definition.
Supports JSON formats.
Allows file upload or URL-based spec import.
Supports various Authentication options: NoAuth, BasicAuth, Bearer Token, OAuth 2.0.
Compatible with Cloud and On-Premise APIs.
Uses DBSync Remote Agent for secure access to internal systems.
Auto-generates CRUD operations from API spec.
Maps and transforms data within DBSync workflows.
Connection Setup
Mode Selection
Cloud
For publicly accessible APIs. Requests are sent directly from DBSync's cloud infrastructure.
On Premise
For internal or private network APIs. Requires configuration of a DBSync Remote Agent.
Agent (Only for On-Premise Mode)
Select a pre-installed Remote Agent that acts as a secure tunnel between your internal API and DBSync.
App Icon (Optional)
Upload a 32x32px jpg or png image to visually identify the connector in your workflow canvas.
Supported Authentication Methods
The OpenAPI Connector supports common API authentication mechanisms, including:
NoAuth
None
Public APIs with no authentication.
BasicAuth
Username, Password
Common for legacy or internal systems.
Bearer Token
Bearer Token
APIs with token-based access.
OAuth 2.0
Grant type, Auth URL, Access Token URL, Client ID, Client Secret, Scope, Redirect URL, State (opt.)
Secure OAuth 2.0-based APIs (e.g., Salesforce, Google).
Authentication types are available for both Cloud and on-premises modes.
Authentication details are configured during connector setup and applied automatically to all API calls.
Prerequisites
Before configuring the OpenAPI Connector, ensure the following:
DBSync Access
A valid license for this connector and access to the DBSync Cloud Workflow platform.
OpenAPI Specification
A valid OpenAPI (Swagger) spec file (JSON or YAML).
API Credentials
Required authentication details.
API Endpoint Accessibility
DBSync must be able to access the API endpoint over the network.
Connector Configuration
Each OpenAPI connector instance represents a connection to a single API definition. If you need to integrate multiple APIs or environments (for example, sandbox and production), create separate connector instances.
After configuration, DBSync parses the OpenAPI specification and makes endpoints available for workflow design.
Quick Setup Guide
Follow these steps to configure the OpenAPI Connector:
Login to DBSync Cloud Workflow
Use your DBSync credentials to access the platform.
Add the OpenAPI Connector
Navigate to the connectors list in the Apps pane and select OpenAPI from the connectors list.
Select Mode
Set up a new connection and choose the deployment Mode (Cloud or On Premise).
Select Type of Authentication
Select an appropriate authentication method (NoAuth, BasicAuth, Bearer Token, or OAuth2.0).
Importing the API Specification
API Specification Type: Choose between JSON or YAML.
Upload a Swagger/OpenAPI file or provide a publicly accessible URL.
Once imported, the connector auto-generates operations based on the defined endpoints.
After completing the setup, validate and save connection:
Click Validate Connection to test API access and authentication.
Click Save Connection to make this API available for workflow automation.
Custom Keys in OpenAPI JSON
x-additional-headers
Let's you inject custom headers (e.g., for authentication) into API calls.
Can reference adapter properties or use hardcoded values.
Example: Few connectors require additional headers. In the example below, we have used Xero as an example.
"x-additional-headers": [
{
"name": "xero-tenant-id",
"type": "value",
"in": "header",
"required": true,
"value": "tenant-id"
}
]
This is an example of Xero.
type →
property → use value from one of the adapter properties
value → use the value as is
in → header
required → true, false
value → property name if type is property or hardcoded value
default → if type is property, required is true, and the property is not found, then use this default value instead
Properties that can be used:
access_token
refresh_token
OAuth_Last_Updated
Any additional property received in the token api call (depends on the app connected)
X-response-strategy
Allows you to paginate the api response.
Paging type tells what kind of pagination is supported.
Supported values for paging type are “page” and “record”.
record → Sets the record number depending on the number of records read. Gets the parameter mentioned in x-page-start from the parameter section of the JSON and adds it to the query if the “in” of the parameter is the query
Example: The below example has a record level. An offset parameter is required in the rest calls for pagination.
The URL will look like: https://www.example.com/orders?offset=0
The offset will increase depending on the records read in the api call. If 10 records are read in the first call, the second call will have offset=10, offset=20, and so on. It will keep increasing until no records are received in the api call.
Example:
"x-response-strategy": {
"x-page-start": "offset",
"x-paging-type": "record"
}
page → sets the page number. Gets the parameter mentioned in x-page-start from the parameter section of the JSON and adds it to the query if the “in” of the parameter is the query
Example: The above example has a page-level pagination. It means that the page number will be added to the query parameters.
The URL will look like: https://www.example.com/orders?page=1
The page number will increase until we receive no records in the response. So subsequent api calls will have parameter page=2, page=3 and so on
Example:
"x-response-strategy": {
"x-page-start": "page",
"x-paging-type": "page"
}
X-jsonpath:
Let's you fine-tune the nested section of the api response to be processed by DBSync.
Unlike others, x-jsonpath must be provided under the response section of each API path. Else, it will pick the first array it finds in the response and use that as the response
Example: The below example shows the sample response from an api. If we need to process the order object from the response, as it has the order detail, we provide "x-jsonpath": "order" as shown below.
{
"page":"1",
"totalPage":100,
"order":[
{
"id":1,
"name":"ABC"
},
{
"id":2,
"name":"XYZ"
}
],
"links":[
{
"url":"/id"
}
]
}
"responses": {
"200": {
"description": "Status 200",
"schema": {
"type": "object",
"$ref": "#/definitions/OneOrder",
"x-jsonpath": "order"
}
}
}
After adding the Custom keys, the query is formed as below, with the correct grouping of the result during the query.
Using the Connector
After saving the connection:
You can customize request inputs, response handling, and map fields.
Use these operations in your DBSync workflows to read and write data.
When Should You Use the OpenAPI Connector?
Use the OpenAPI Connector when:
You want to integrate with a third-party or internal REST API that provides a Swagger/OpenAPI definition.
You require a custom connector without building one from scratch.
You want to quickly auto-generate operations for APIs and include them in your workflows.
You need to access private or internal APIs using DBSync's Remote Agent.
Error Handling
Common Issues
401 Unauthorized: Double-check your authentication credentials and token validity.
Invalid Parameters: Ensure that all required parameters and body fields are correctly configured as per the OpenAPI specification.
Timeout Errors: Increase the timeout setting in DBSync if API calls are taking longer to respond.
Debugging Tips
Log Responses: Enable response logging in DBSync to view API responses for troubleshooting.
Test Environment: Run initial tests in a staging environment to avoid unintended changes in production.
Best Practices
Secure Credentials: Use encrypted storage for API keys and sensitive data.
Optimize Payloads: Only send the required data in API requests to improve performance.
Monitor Usage: Track API call limits to prevent reaching the rate limits imposed by the service.
The OpenAPI Connector in DBSync Cloud Workflow is a powerful tool for integrating with custom RESTful APIs defined by OpenAPI specifications. By following this guide, you can automate and manage data flows between DBSync and any API-compatible service to enhance your workflow capabilities.
Frequently Asked Questions (FAQ)
Do I need to write code to use the OpenAPI Connector? No, workflows are configured using DBSync’s UI once the OpenAPI spec is provided.
What OpenAPI versions are supported? The connector supports OpenAPI (Swagger) 2.0 and 3.x specifications.
What file types are supported for Swagger import?
JSON and YAML are both supported.
Can I use this connector with internal systems?
Yes, use the On-Premise mode with DBSync Remote Agent installed.
Why isn't my Swagger file generating operations?
Ensure the file is properly formatted according to OpenAPI 2.0 or 3.0 standards.
Do I need to redeploy the connector after editing the Swagger file?
Yes, any update to the spec requires re-validation and saving the connection.
Is OAuth supported? Yes, OAuth 2.0 is supported where defined in the API specification.
Can I call multiple endpoints in one workflow? Yes, workflows can include multiple API calls across different steps.
Summary
The OpenAPI Connector in DBSync Cloud Workflow provides a powerful, standards-based approach to integrating any REST API into your automation workflows. By leveraging OpenAPI specifications, it enables rapid integration, reduces development effort, and extends DBSync’s reach beyond pre-built connectors - all while maintaining security, flexibility, and scalability.
Useful Links
Remote Agent - Used for accessing on-premise APIs securely.
ReST Action - Used within workflows to execute specific operations (like GET, POST, PUT, DELETE, PATCH, and HEAD) defined in the imported API schema.
Last updated