OpenAPI
This guide provides a comprehensive overview of how to set up, configure, and utilize the OpenAPI Connector effectively within the DBSync Cloud Workflow platform.
Last updated
This guide provides a comprehensive overview of how to set up, configure, and utilize the OpenAPI Connector effectively within the DBSync Cloud Workflow platform.
Last updated
The OpenAPI Connector in DBSync Cloud Workflow is a powerful tool designed to enable seamless integration with any RESTful API described by an OpenAPI (formerly Swagger) specification. By leveraging this connector, you can automate interactions with external services, enhancing the scope and flexibility of your workflows. Whether you're synchronizing data, triggering events, or performing complex API-driven tasks, the OpenAPI Connector ensures that your integrations are efficient and reliable.
Log in to your DBSync Cloud Workflow dashboard.
Navigate to Apps > Add App displayed on the OpenAPI from the list of available connectors.
In the Quick Setup tab, specify the Authentication Type and the respective Credentials.
Click Validate Connection to confirm the authenticity and accuracy of the connection that you want to establish.
Once the validation is successful, click Connect and then click Save Connection for future use.
The Quick Setup provides a streamlined way to configure API integration. It allows users to quickly define the API URL, upload or link the API JSON, define additional credentials, and select the authentication type. This tab simplifies the setup process by auto-populating available API endpoints and methods, enabling faster workflow creation with minimal manual configuration.
This option is used when the API does not require authentication. It works for public endpoints or testing environments.
API URL: This is the base URL of the RESTful API you want to connect. It serves as the endpoint for sending requests and retrieving data from the API. It defines the location of the resource you want to interact with and usually includes the protocol (e.g., https://), domain, and path (e.g., https://api.example.com/v1/resource).
API JSON: This refers to the OpenAPI specification file, provided in JSON format, which describes the API's endpoints, methods, request parameters, and response structures. It is used to configure the integration and map the available actions.
This method uses a username and password, encoded in Base64, to authenticate API requests. It's suitable for straightforward scenarios but less secure unless combined with HTTPS.
Username: Username credential required for authenticating API requests.
Password: Appropriate password for the username mentioned above to access the API request.
API URL or API JSON: Refer to NoAuth Authentication for the description.
This authentication type is a robust and secure authentication standard commonly used for accessing third-party APIs. It involves exchanging client credentials for an access token via an authorization server, offering token-based access with varying levels of permissions.
Grant Type: Specifies the method used to obtain an access token from the authorization server.
Authorization Code: The Authorization Code grant type is used for user-based authentication, requiring user interaction. The user logs in and grants permission, after which the API provider issues an authorization code. DBSync then exchanges this code for an access token, which is used to authenticate API requests securely.
Auth URL: The endpoint URL where the user is redirected to authenticate and grant access to the application.
Access Token URL: The endpoint URL used to exchange the authorization code for an access token after user authentication.
Client ID: A unique identifier for the application registered with the authorization server.
Client Secret: A secret key assigned to the application, used for secure communication with the authorization server.
Scope: A list of permissions or access levels requested by the application during authentication.
Redirect URL: The callback URL where the authorization server sends the user after successful authentication.
State: A unique value sent by the application to maintain session integrity and prevent cross-site request forgery (CSRF) attacks.
API Specification Type: Format used to define the API structure and authentication details. This specification outlines the API's endpoints, request and response formats, authentication methods, and other integration details.
Client Credentials: The Client Credentials grant type is used for machine-to-machine authentication without user interaction. DBSync sends a request using a client ID and client secret, and the API provider verifies them before issuing an access token. This token is then used to authenticate API requests in automated workflows.
Access Token URL: The endpoint URL used to exchange the authorization code for an access token after user authentication.
Client ID: A unique identifier for the application registered with the authorization server.
Client Secret: A secret key assigned to the application, used for secure communication with the authorization server.
Scope: A list of permissions or access levels requested by the application during authentication.
Redirect URL: The callback URL where the authorization server sends the user after successful authentication.
State: A unique value sent by the application to maintain session integrity and prevent cross-site request forgery (CSRF) attacks.
API Specification Type: Format used to define the API structure and authentication details. This specification outlines the API's endpoints, request and response formats, authentication methods, and other integration details.
This method uses a token-based authentication method where the client provides a bearer token in the request header (usually Authorization: Bearer <token>). This token grants access to the API without needing to send username and password for every request.
Bearer Token: A secure token used for authentication, typically passed in the HTTP Authorization header.
API URL: The endpoint URL of the API to which requests are made using Bearer authentication.
API JSON: The payload or response structure in JSON format exchanged during API interactions.
NOTE: Ensure that you Save Connection after you validate the Authentication Type.
Use Dynamic Headers to pass custom header values at runtime by configuring them in the connector setup.
Add Custom Query Parameters as needed by the API to filter or modify requests dynamically.
Response Mapping: Configure response mappings to parse and use data from API responses in subsequent workflow steps.
Error Handling: Implement conditional steps to handle response codes (e.g., 200 OK, 404 Not Found, 500 Internal Server Error).
The OpenAPI Connector enables you to perform a wide range of API operations, including GET, POST, PUT, DELETE, and others. Below are some versatile use cases:
Use Case 1: Fetch Data from an API (GET Request)
Create a Project in DBSync.
Add a ReST action and name the operation.
Select the GET operation from the available API actions.
Configure the required parameters, such as query strings, headers, or path variables.
Save and test the action to fetch data from the API.
Use Case 2: Submit Data to an API (POST Request)
Create a Project in DBSync.
Add a ReST action and name the operation.
Select the POST operation from the list of available API actions.
Specify the request body in JSON format and configure headers as required.
Map source data fields to the request payload fields using DBSync's field mapping tools.
Save, test, and execute the Workflow to submit data to the API.
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.
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.
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 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.
