Skip to content

Connector SDK Overview

The Connector SDK is a set of tools for building, testing, and publishing custom connectors. It allows platform administrators (and enterprise administrators with the right permissions) to add new system integrations to the DIBOP catalogue.

What Is the Connector SDK?

The Connector SDK provides:

  • A Connector Builder UI for creating connector templates without writing code
  • AI-assisted import for generating connector configurations from API documentation
  • A testing harness for validating connectors before publishing
  • A publishing workflow for making connectors available to enterprises

Who Uses It?

The Connector SDK is primarily for Platform Admins, who maintain the shared connector catalogue. In some configurations, Enterprise Admins may also be granted access to build connectors for their own enterprise.

User What They Can Do
Platform Admin Build connectors, publish to the shared catalogue, manage all connector templates
Enterprise Admin (if enabled) Build connectors scoped to their own enterprise, submit for platform review
Viewer Browse published connectors (no SDK access)

Connector Lifecycle

A connector moves through these stages:

Design  →  Configure  →  Test  →  Publish  →  Maintain

1. Design

Decide what the connector should do:

  • Which external system does it connect to?
  • What authentication method does the system use?
  • Which API operations should be available?
  • How should fields map to the Canonical Data Model?

2. Configure

Use the Connector Builder to configure:

  • System name, slug, and type
  • Base URL and authentication scheme
  • API operations (endpoints, methods, parameters)
  • Resilience settings (timeout, retries, rate limits)

3. Test

Before publishing, test the connector:

  • Use the built-in test harness to validate each operation
  • Test with real or mock API responses
  • Verify field mappings produce correct CDM data

4. Publish

Make the connector available:

  • Draft connectors are only visible to the creator
  • Published connectors appear in the catalogue for all enterprises
  • Enterprise-scoped connectors are visible only within their enterprise

5. Maintain

After publishing:

  • Update the connector when the external system's API changes
  • Add new operations as they become available
  • Fix mapping issues reported by users

Browsing the SDK

Navigate to SETTINGS > Connector SDK (or Platform Config > Connector SDK for Platform Admins) in the sidebar.

The SDK landing page shows:

Section Description
My Connectors Connectors you have created (draft and published)
All Connectors All connectors in the catalogue (Platform Admin only)
Recent Activity Recent changes to connector templates

Connector Card

Each connector is shown as a card with:

  • System name and icon
  • Status (Draft / Published)
  • Number of operations
  • Last updated date
  • Author

What Makes a Good Connector?

A well-built connector:

  1. Covers the key operations -- includes the API operations that users will need most
  2. Has accurate field mappings -- maps native fields to the CDM correctly, with verified status
  3. Handles authentication properly -- supports the external system's auth mechanism with credential rotation
  4. Is resilient -- has appropriate timeout, retry, and rate limit settings
  5. Is well documented -- includes clear descriptions for each operation and field

Connector Template Structure

Under the hood, a connector template is a structured JSON document:

{
  "slug": "mercedes-benz-oneapi",
  "name": "Mercedes-Benz OneAPI",
  "type": "OEM",
  "base_url": "https://api.mercedes-benz.com",
  "auth": {
    "type": "oauth2",
    "credential_schema": {
      "client_id": { "type": "string", "required": true },
      "client_secret": { "type": "string", "required": true, "sensitive": true },
      "token_url": { "type": "string", "required": true }
    }
  },
  "operations": [
    {
      "name": "search_vehicles",
      "method": "GET",
      "path": "/vehicles",
      "parameters": { ... },
      "response_schema": { ... }
    }
  ],
  "resilience": {
    "timeout_seconds": 30,
    "max_retries": 3,
    "rate_limit_per_minute": 60
  }
}

You do not need to write this JSON directly -- the Connector Builder UI generates it for you.

Built-In Connectors

DIBOP ships with several built-in connectors that you can use as reference when building your own:

Connector Auth Type Operations Notes
NHTSA VPIC None 3 Public API, no credentials needed
REST Countries None 2 Public API
ExchangeRate API API Key 2 Simple API key auth
HTTPBin None 4 Testing utility
Open-Meteo None 1 Weather data

Browse any built-in connector in the SDK to see how it is configured.

Next Steps