Skip to Content

Connector SDK REST APIs

Overview

These APIs are available for registering and managing connectors created with the Connector SDK. Examples of using these APIs with Postman are shown on the Registration page.

Method Description
Log In User Log in to Harmony
Register a Connector Register a custom connector
List Registered Connectors List registered connectors
Delete Registration Delete a connector registration
Delete Payload Delete a connector payload
Validate Connector Key/Secret Validate a connector key and secret

Note

To completely delete a connector from an organization, you need to delete both the registration and the JSON payload. You can delete only those connectors that are not used in any projects of the organization.

Base URL

All APIs listed below use a base URL composed of

{hostURL}/jitterbit-cloud-restful-service/

where

  • {hostURL}: The Jitterbit region host URL, such as https://na-east.jitterbit.com

Preface each URL given for each API with this base URL (represented by {baseURL}). To determine which region your organization is in, see Finding My Region.

The host URL for each region is given by this table:

Region Host URL
NA https://na-east.jitterbit.com
EMEA https://emea-west.jitterbit.com
APAC https://apac-southeast.jitterbit.com

Authentication

In addition to the Base URL, all APIs listed below—with the exception of Log in to Harmony—assume that an authentication token is passed as one of the headers in the request. This token can be obtained by using the first API and extracting the token from its response.

Request headers

With the exception of Log in to Harmony, all APIs listed below are to include these request headers (in addition to any headers described for a particular API):

Content-Type: application/json
authToken: {authToken}

where

Log in to Harmony

Logs in to Harmony. Use this API to obtain the authentication token needed for using the other APIs listed on this page.

PUT {baseURL}/user/login

where

Request headers

  • Content-Type: application/json

Request body

The body of the request must contain:

{
  "email": "{email}",
  "password": "{password}"
}

where

  • {email}: The username (email address) associated with the Harmony login
  • {password}: The password for the username

Response

The body of the response will be a JSON string containing an authenticationToken. This token is to be passed as the authToken header of subsequent API calls and will authenticate those calls.

Register a custom connector

Registers a connector and obtains the IDs required for the connector manifest file. Run this API prior to packaging the connector JAR file.

POST {baseURL}/orgs/{orgId}/connector

where

  • {baseURL}: The base URL, as described above
  • {orgId}: Organization ID of the Harmony org in which the connector is registered

Request headers

Request Body

The body of the request must contain:

{
    "name": "{connectorName}",
    "version": "{connectorVersion}"
}
where

  • {connectorName}: The name of the connector
  • {connectorVersion}: The version of the connector

Response

The body of the response will contain a JSON string with the IDs, key, and secret required for the connector manifest file. For example:

{
    "status": true,
    "operation": "Register a connector",
    "id": "4471",
    "key": "6d093654-d...2-10cad6797d6e",
    "secret": "3673e11b-f...d-5e3f3ad796d5",
    "endpointEntityId": "2370701",
    "functionEntityStartId": "2370702",
    "functionEntityEndId": "2370800"
}

List registered connectors

Lists all custom connectors (those created with either the Connector SDK or the Connector Builder) registered with a particular organization.

GET {baseURL}/orgs/{orgId}/connector

where

  • {baseURL}: The base URL, as described above
  • {orgId}: Organization ID of the Harmony org in which the connector is registered

Request headers

Response

The body of the response will contain a JSON string with a list of registered connectors. This example shows an org with the example Dropbox connector registered:

{
    "status": true,
    "operation": "List registered connectors",
    "registeredConnectorList": [
        {
            "id": "4471",
            "name": "Dropbox",
            "version": "1.0.0",
            "key": "6d093654-d...2-10cad6797d6e",
            "secret": "3673e11b-f...d-5e3f3ad796d5",
            "endpointEntityId": "2370701",
            "functionEntityStartId": "2370702",
            "functionEntityEndId": "2370800"
        }
    ]
}

Delete a connector registration

Deletes the registration of a custom connector. This API will succeed only if the connector is not used in any projects in the organization. To delete the JSON payload (the JSON file describing the UI, given in the manifest entry Jitterbit-Connector-UI) of a custom connector, use the API to delete a connector payload.

DELETE {baseURL}/orgs/{orgId}/connector/{connectorId}

where

  • {baseURL}: The base URL, as described above
  • {orgId}: Organization ID of the Harmony org in which the connector is registered
  • {connectorId}: Connector ID, obtained when the connector was registered

Request headers

Delete a connector payload

Deletes the JSON payload (the JSON file describing the UI, given in the manifest entry Jitterbit-Connector-UI) of a custom connector. The payload is cached at Harmony in order to render the Integration Studio UI of the connector. This API will succeed only if the connector is not used in any projects in the organization. To delete the registation of a custom connector, use the API to delete a connector registration.

DELETE {baseURL}/orgs/{orgId}/connector/{connectorId}/sdk/delete

where

  • {baseURL}: The base URL, as described above
  • {orgId}: Organization ID of the Harmony org in which the connector is registered
  • {connectorId}: Connector ID, obtained when the connector was registered

Request headers

Validate a connector key and secret

Validates a connector key and secret pair.

PUT {baseURL}/orgs/{orgId}/connector/validate/securityinfo

where

  • {baseURL}: The base URL, as described above
  • {orgId}: Organization ID of the Harmony org in which the connector is registered

Request headers

Request body

The body of the request must contain:

{
    "name": "{connectorName}",
    "key": "{key}",
    "secret": "{secret}"
}

where

  • {connectorName}: The name of the connector
  • {key}: The key associated with the connector of that name
  • {secret}: The secret associated with the connector of that name