Connectors

A Connector is a production-ready integration with Composable Commerce.

After a ConnectorStaged is published, 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

ConnectorSearchPagedQueryResponse

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.
`integrationTypes` Array of IntegrationType	Integration types of the Connector. Can be used to filter search and query results.
`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 published Connector. The `isPreviewable` field of the ConnectorStaged must be `true` to reference a previewable ConnectorStaged. Default: `false`

Example: json

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

ConnectorSearchPagedQueryResponse

PagedQueryResult with results containing an array of Connector.

`limit` Int	The maximum number of Connectors returned.
`offset` Int	The offset of the Connectors returned.
`count` Int	The number of Connectors returned.
`total` Int	The total number of Connectors matching the query.
`results` Array of Connector	Connectors matching the query.

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",
  "integrationTypes": ["other"],
  "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",
  "integrationTypes": ["other"],
  "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 are based on matches found in the `name` and `description` fields of a Connector.
`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.
`integrationTypes` IntegrationType	Only search for Connectors with a specified `integrationType`. The parameter can be passed multiple times.

Response:

200ConnectorSearchPagedQueryResponseasapplication/json

Request Example:cURL

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

200 Response Example: ConnectorSearchPagedQueryResponsejson

{
  "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",
      "integrationTypes": ["other"],
      "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
    }
  ]
}