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

authToken: Authorization token obtained from logging in to Harmony

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

{baseURL}: The base URL, as described above

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¶

authToken: Authorization token obtained from logging in to Harmony

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¶

authToken: Authorization token obtained from logging in to Harmony

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¶

authToken: Authorization token obtained from logging in to Harmony

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 Cloud 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¶

authToken: Authorization token obtained from logging in to Harmony

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¶

authToken: Authorization token obtained from logging in to Harmony

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