Raise an IssueJoin Community

OpenAPI

Overview: What is OpenAPI?

OpenAPI is a standard specification for defining RESTful APIs. Formerly known as Swagger, it enables developers to describe the API structure, endpoints, methods, request/response formats, and authentication types in a machine-readable format. This promotes easier documentation, testing, and integration.

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 of the OpenAPI Connector

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, and DELETE based on the imported specification. Users can then utilize these operations in their workflows to automate data movement and interactions across systems.

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.

Building a Custom Connector with OpenAPI

  1. Set up a new connection and choose the deployment mode (Cloud or On Premise).

  2. Select an appropriate authentication method (NoAuth, BasicAuth, Bearer Token, or OAuth2.0).

  3. Upload or link to the Swagger/OpenAPI file.

  4. Validate the connection.

  5. Save the configuration.

  6. Use the auto-generated operations within your workflows.

Supported Features

  • Connects to any REST API with a valid OpenAPI (Swagger) definition.

  • Supports JSON formats.

  • Allows file upload or URL-based spec import.

  • 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

Mode
Description

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 image to visually identify the connector in your workflow canvas.

Authentication Methods

Type
Required Fields
Use Case

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

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.

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.

Validate and Save Connection

After completing the setup:

  • 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

  • Let's you 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 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 needs to be provided under the response section of each API path. If not provided, 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.

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.

FAQs & Troubleshooting

Q: What file types are supported for Swagger import? A: JSON and YAML are both supported.

On-PremiseQ: Can I use this connector with internal systems? A: Yes, use the On-Premise mode with DBSync Remote Agent installed.

Q: Why isn't my Swagger file generating operations? A: Ensure the file is properly formatted according to OpenAPI 2.0 or 3.0 standards.

Q: Do I need to redeploy the connector after editing the Swagger file? A: Yes, any update to the spec requires re-validation and saving the connection.

Useful Links:

  • Remote Agent – Used for accessing on-premise APIs securely. Installation & Setup Guide

  • ReST Action – Used within workflows to execute specific operations (like GET, POST, PUT, DELETE) defined in the imported API schema. How to Use ReST Actions

PreviousNetSuite Connector SettingsNextPointClickCare

Last updated