Connectors

Connectors represent a certified and listed integration that can be deployed by clients.

After a ConnectorStaged is certified, a Connector is created containing all the information from the ConnectorStaged. These are production versions of your Connector that are available for clients to deploy.

Connectors are read-only. If you are a creator and want to make changes to your Connector, you should make the changes to the ConnectorStaged and then use the Publish update action.

Representations

Connector

ConnectorReference

Connector

`id` String	Unique identifier of the Connector.
`version` Int	Current version of the Connector.
`key` String	User-defined unique identifier of the Connector. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` String	Name of the Connector.
`description` String	Description of the Connector.
`creator` Creator	Owner of the Connector.
`repository` Repository	GitHub repository details of the Connector.
`configurations` Array of ConnectorConfigurationApplication	Configurations needed by Connectors for hosting. Loaded as environment variables in the workload.
`private` Boolean	If `true`, only Composable Commerce Projects specified in `privateProjects` can access the Connector.
`supportedRegions` Array of Region	If not empty, Connectors can only be deployed in these Regions. If empty, Connectors can be deployed in any supported Region.
`certified` Boolean	If `true`, the Connector is certified.
`documentationUrl` String	URL to the documentation of the Connector.

ConnectorReference

Reference to a Connector. Either id or key is required.

`id` String	Unique identifier of the referenced Connector.
`version` Int	Version of the referenced Connector.
`key` String	User-defined unique identifier of the referenced Connector.
`staged` Boolean	If `true`, the previewable ConnectorStaged will be referenced instead of the certified Connector. The `isPreviewable` field of the ConnectorStaged must be `true` to reference a previewable ConnectorStaged. Default: `false`

Example: json

{
  "key": "connector-key",
  "version": 1
}

Get Connector

Get Connector by ID

GET

https://connect.{region}.commercetools.com/connectors/{id}

OAuth 2.0 Scopes:

manage_project:{projectKey} , manage_connectors:{projectKey} , view_connectors:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`id` String	`id` of the Connector

Response:

200Connectorasapplication/json

Request Example:cURL

curl --get https://connect.{region}.commercetools.com/connectors/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: Connectorjson

{
  "id": "5ab3edcd-9d23-4934-8f48-256805253119",
  "key": "connector-key",
  "version": 1,
  "name": "Connector's name",
  "description": "Connector's description",
  "creator": {
    "title": "Mr",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "commercetools",
    "noOfContributors": 200
  },
  "repository": {
    "url": "git@github.com:commercetools/connect-application-kit.git",
    "tag": "0.0.0"
  },
  "configurations": [
    {
      "applicationName": "app-1",
      "applicationType": "service",
      "standardConfiguration": [
        {
          "key": "CONFIG_KEY",
          "description": "config key description"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CONFIG_SECRET_KEY",
          "description": "config secret description"
        }
      ]
    }
  ],
  "private": false,
  "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
  "certified": true
}

Get Connector by Key

GET

https://connect.{region}.commercetools.com/connectors/key={key}

OAuth 2.0 Scopes:

manage_project:{projectKey} , manage_connectors:{projectKey} , view_connectors:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`key` String	`key` of the Connector

Response:

200Connectorasapplication/json

Request Example:cURL

curl --get https://connect.{region}.commercetools.com/connectors/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: Connectorjson

{
  "id": "5ab3edcd-9d23-4934-8f48-256805253119",
  "key": "connector-key",
  "version": 1,
  "name": "Connector's name",
  "description": "Connector's description",
  "creator": {
    "title": "Mr",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "commercetools",
    "noOfContributors": 200
  },
  "repository": {
    "url": "git@github.com:commercetools/connect-application-kit.git",
    "tag": "0.0.0"
  },
  "configurations": [
    {
      "applicationName": "app-1",
      "applicationType": "service",
      "standardConfiguration": [
        {
          "key": "CONFIG_KEY",
          "description": "config key description"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CONFIG_SECRET_KEY",
          "description": "config secret description"
        }
      ]
    }
  ],
  "private": false,
  "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
  "certified": true
}

Search Connectors

GET

https://connect.{region}.commercetools.com/connectors/search

Retrieves all available Connectors.

OAuth 2.0 Scopes:

manage_project:{projectKey} , manage_connectors:{projectKey} , view_connectors:{projectKey}

Path parameters:

region

String

Region in which the Project is hosted.

Query parameters:

`text` String	The text to search for. For example, as supplied by a user through a search input field. Search results will be based on if the `name` and `description` fields of a Connector contain this text.
`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`sort` String	The parameter can be passed multiple times.
`private` Boolean	If `true` then only Connectors assigned to your Project are retrieved. If `false` then all available Connectors are retrieved.
`creator.company` String	Company name of a creator to search for.
`id` String	`id` of a Connector to search for. The parameter can be passed multiple times.
`key` String	`key` of a Connector to search for. The parameter can be passed multiple times.

Response:

200

Paged

asapplication/json

Request Example:cURL

curl --get https://connect.{region}.commercetools.com/connectors/search -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: Pagedjson

{
  "offset": 0,
  "limit": 20,
  "total": 1,
  "count": 1,
  "results": [
    {
      "id": "5ab3edcd-9d23-4934-8f48-256805253119",
      "key": "connector-key",
      "version": 1,
      "name": "Connector's name",
      "description": "Connector's description",
      "creator": {
        "title": "Mr",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "company": "commercetools",
        "noOfContributors": 200
      },
      "repository": {
        "url": "git@github.com:commercetools/connect-application-kit.git",
        "tag": "0.0.0"
      },
      "configurations": [
        {
          "applicationName": "app-1",
          "applicationType": "service",
          "standardConfiguration": [
            {
              "key": "CONFIG_KEY",
              "description": "config key description"
            }
          ],
          "securedConfiguration": [
            {
              "key": "CONFIG_SECRET_KEY",
              "description": "config secret description"
            }
          ]
        }
      ],
      "private": false,
      "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
      "certified": true
    }
  ]
}