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
Set up a new connection and choose the deployment mode (Cloud or On Premise).
Select an appropriate authentication method (NoAuth, BasicAuth, Bearer Token, or OAuth2.0).
Upload or link to the Swagger/OpenAPI file.
Validate the connection.
Save the configuration.
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
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
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).
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.
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
Last updated