Skip to content

Connector Builder

The Connector Builder is the primary tool for creating and editing connector templates. It provides a tabbed interface for configuration, AI-assisted import from documentation, and integrated testing.

Accessing the Builder

There are two ways to open the Connector Builder:

  1. Create New: Navigate to the Connector SDK page and click Create Connector
  2. Edit Existing: Click on any connector card and select Edit

Builder Interface

The Builder has five tabs:

Tab Purpose
Overview Name, slug, type, description, base URL, icon
Auth & Credentials Authentication type and credential schema
Operations API endpoint definitions
Resilience Timeout, retries, circuit breaker, rate limits
Test Live testing of operations

Navigation between tabs preserves your work. Click Save at any time to persist your changes.

Import from Docs (AI-Powered)

The fastest way to create a connector is to let the AI extract the configuration from the external system's API documentation.

How It Works

  1. In the Overview tab, click Import from Docs
  2. Paste the URL of the external system's API documentation
  3. Click Analyse

  4. The AI reads the documentation and extracts:

    • System name and description
    • Base URL
    • Authentication method and credential requirements
    • API operations (endpoints, methods, parameters)
    • Response schemas (where documented)

  5. Review the extracted configuration

  6. Approve or adjust each section
  7. The Builder is populated with the extracted configuration

What the AI Extracts

Section Extraction Quality
Base URL Usually excellent -- clearly stated in most API docs
Auth type Good -- most docs clearly describe authentication
Operations Good for well-structured docs (OpenAPI, Swagger); less reliable for prose-only docs
Parameters Good for documented parameters; may miss optional/advanced parameters
Response schema Variable -- depends on how well the docs describe responses

Best Results

The AI works best with structured API documentation (Swagger, OpenAPI, ReadMe.io). For APIs documented only in prose, you may need to manually supplement the AI's output.

Import from OpenAPI Spec

If the external system provides an OpenAPI (Swagger) specification, you can import it directly:

  1. In the Overview tab, click Import OpenAPI
  2. Either:
    • Paste the OpenAPI JSON/YAML content
    • Enter the URL of the OpenAPI spec endpoint
  3. Click Import
  4. The Builder is populated with all operations, parameters, and schemas from the spec

OpenAPI import is the most reliable import method because the specification is machine-readable and unambiguous.

Manual Configuration

For APIs without structured documentation, configure each section manually using the tabbed interface. See Creating a Connector for a step-by-step guide.

Operations Editor

The Operations tab provides a visual editor for each operation:

┌──────────────────────────────────────────────────┐
│  Operation: get_current_weather                   │
│  ─────────────────────────────────────────────── │
│  Method: [GET ▼]    Path: /data/2.5/weather      │
│  Description: Returns current weather data        │
│                                                   │
│  Parameters:                                      │
│  ┌──────────┬──────────┬──────────┬───────────┐  │
│  │ Name     │ Location │ Type     │ Required  │  │
│  ├──────────┼──────────┼──────────┼───────────┤  │
│  │ q        │ query    │ string   │ Yes       │  │
│  │ units    │ query    │ string   │ No        │  │
│  │ lang     │ query    │ string   │ No        │  │
│  └──────────┴──────────┴──────────┴───────────┘  │
│  [+ Add Parameter]                                │
│                                                   │
│  Response Schema: [Edit JSON Schema]              │
└──────────────────────────────────────────────────┘

JSON Editor

For advanced users, a JSON Mode toggle switches the entire Builder to a raw JSON editor. This is useful for:

  • Bulk editing multiple operations
  • Copy-pasting configurations from other connectors
  • Fine-tuning details not exposed in the visual editor

Testing in the Builder

The Test tab lets you validate your connector before publishing.

Setting Up Test Credentials

  1. Open the Test tab
  2. Enter credentials for the external system
  3. These credentials are used only for testing and are not stored permanently

Testing an Operation

  1. Select an operation from the dropdown
  2. Fill in the required parameters
  3. Click Send Request
  4. View the results:
Section Description
Status HTTP status code and reason
Duration Response time in milliseconds
Headers Response headers
Body Response body (formatted JSON)
Validation Whether the response matches the expected schema

Automated Test Suite

Click Run All Tests to execute a test for each operation with default or sample parameters. This runs the same test harness used for connector certification.

The test suite validates:

Category What Is Tested
Connectivity Can DIBOP reach the base URL?
Authentication Do the credentials authenticate successfully?
Operations Does each operation return a successful response?
Response Schema Does each response match the expected schema?
Error Handling Does the connector handle error responses correctly?
Resilience Do timeout and retry settings work as configured?
Rate Limiting Does the connector respect rate limits?
Field Mapping Do CDM mappings produce valid canonical records?
Idempotency Can operations be safely retried?

Builder Tips

Start with Import

Even if the AI import is not perfect, it provides a solid starting point that is faster to refine than building from scratch.

Test Frequently

Test after configuring each operation, not just at the end. This catches issues early.

Use the Preview

Each operation has a Preview button that shows how the HTTP request will be constructed. Use this to verify:

  • The full URL (base URL + path + query parameters)
  • Headers (including auth headers)
  • Request body format

Copy from Existing

If you are building a connector similar to an existing one, use Clone Connector from the SDK landing page. This creates a copy with the same structure that you can modify.

Keyboard Shortcuts

Shortcut Action
Ctrl+S Save the connector template
Ctrl+T Open the Test tab
Ctrl+Enter Send test request (when in Test tab)
Tab Move between form fields

Next Steps