SAP Cloud Platform Open Connectors

Connectors

List Connector

GET /elements

Retrieve a list of connector.

Query Parameters

nextPageThe next page token. Found in the header of the previous search.
pageSizeThe page size for the paginated results, defaults to 200. Maximum 200.

Response Fields

The table below shows an abbreviated list of response fields.

idThe connector id is a unique numeric identifier for the connector, distinct from the connector key, which is alphanumeric.
nameThe display name of the connector.
keyThe connector key is a unique alphanumeric identifier for the connector, distinct from the connector id, which is numeric.
descriptionA brief description of the connector.
imageThe branded image associated with the connector.
configurationObject containing the configuration of the connector.
transformationsEnabled
Indicates whether resources at the API provider can be mapped to a common resource.
bulkDownloadEnabled/
bulkUploadEnabled
Indicates whether the connector supports bulk.
extendableIndicates whether you can extend the connector by adding resources.
authentication
Identifies the type of authentication used.
extended
Identifies whether you have added resources to the connector or not.
hubThe hub in which the connector is categorized.
privateIndicates whether the connector is part of the public connector catalog or not.

Example Request

curl -X GET \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response

[
  {
    "id": 3128,
    "name": "Recurly",
    "key": "recurly",
    "description": "Add a Recurly Instance to connect your existing recurly account to the Billing Hub, allowing you to manage customers, invoices, and transactions across multiple connectors. You will need your Recurly account to add an instance.",
    "image": "https://cloud.githubusercontent.com/assets/4119349/24875787/7ff95a3a-1de6-11e7-86c4-b844167212c1.png",
    "active": true,
    "deleted": false,
    "typeOauth": false,
    "trialAccount": false,
    "configuration": [],
    "transformationsEnabled": true,
    "bulkDownloadEnabled": true,
    "bulkUploadEnabled": true,
    "cloneable": true,
    "extendable": false,
    "beta": false,
    "authentication": {
      "type": "custom"
    },
    "extended": false,
    "hub": "billing",
    "protocolType": "http",
    "private": false
  }
]

Retrieve the OpenAPI Schema

GET /elements/{id}/docs

Retrieve the OpenAPI version 2 schema for an connector by connector id. Specify an operationId to return only a specific endpoint.

Path Parameters

idThe connector id is a unique numeric identifier for the connector, distinct from the connector key, which is alphanumeric.

Query Parameters

operationId
A unique string used that identifies a specific endpoint. For example, the OpenAPI specification for Salesforce Sales Cloud includes operationIDs like getAccountsActivities, createAccount, updateCampaignById, and many more.

Response Fields

For descriptions see the OpenAPI specification.

Example Request

curl -X GET \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements/23/docs?operationId=getAccountsActivities \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response

The response includes the OpenAPI specification file in the body.  The following example is an abbreviated version.


{  
  "basePath":"/elements/api-v2/hubs/crm",
  "paths":{  },
  "host":"console.cloud-elements.com",
  "schemes":[  ],
  "definitions":{  },
  "swagger":"2.0",
  "info":{  },
  "tags":[  ]
}

Retrieve an Connector's Metadata

GET /elements/{id}/metadata

Retrieve the metadata of a specific element by connector id.

Path Parameters

idThe connector id is a unique numeric identifier for the connector, distinct from the connector key, which is alphanumeric.

Response Fields

The table below shows an abbreviated list of response fields.

idThe connector id is a unique numeric identifier for the connector, distinct from the connector key, which is alphanumeric.
nameThe display name of the connector.
keyThe connector key is a unique alphanumeric identifier for the connector, distinct from the connector id, which is numeric.
descriptionA brief description of the connector.
authenticationType
Identifies the type of authentication used.
eventsAn object that identifies whether events are supported and, if so, what kind (webhooks or polling).

Example Request

curl -X GET \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements/23/metadata \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response


{
    "id": 23,
    "name": "Salesforce Sales Cloud",
    "key": "sfdc",
    "displayOrder": 100,
    "active": false,
    "beta": false,
    "description": "Add a Salesforce Instance to connect your existing Salesforce account to the CRM Hub, allowing you to manage contacts, leads, accounts, opportunities etc. across multiple CRM connectors or your other Salesforce services. You will need your Salesforce account information to add an instance.",
    "transformations": false,
    "churros": false,
    "normalizedPaging": false,
    "swaggerValidated": false,
    "cloneable": false,
    "authenticationType": "custom",
    "events": {
        "supported": true,
        "methods": [
            "polling"
        ]
    },
    "resources": []
}

Retrieve a Specific Connector

GET /elements/{keyOrId}

Retrieve a specific connector by connector id or connector key.

Path Parameters

keyOrIdThe connector key is a unique alphanumeric identifier for the connector, while the connector id is a unique numeric identifier for the connector. Replace keyOrId with either identifier.

Response Fields

The table below shows an abbreviated list of response fields.

idThe connector id is a unique numeric identifier for the connector, distinct from the connector key, which is alphanumeric.
nameThe display name of the connector.
keyThe connector key is a unique alphanumeric identifier for the connector, distinct from the connector id, which is numeric.
descriptionA brief description of the connector.
imageThe branded image associated with the connector.
configurationObject containing the configuration of the connector.
transformationsEnabled
Indicates whether resources at the API provider can be mapped to a common resource.
bulkDownloadEnabled/
bulkUploadEnabled
Indicates whether the connector supports bulk.
extendableIndicates whether you can extend the connector by adding resources.
authentication
Identifies the type of authentication used.
extended
Identifies whether you have added resources to the connector or not.
hubThe hub in which the connector is categorized.
privateIndicates whether the connector is part of the public connector catalog or not.

Example Request

curl -X GET \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements/sfdc \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response


{  
  "id":23,
  "name":"Salesforce Sales Cloud",
  "hookName":"Salesforcecom",
  "key":"sfdc",
  "description":"Add a Salesforce Instance to connect your existing Salesforce account to the CRM Hub, allowing you to manage contacts, leads, accounts, opportunities etc. across multiple CRM connectors or your other Salesforce services. You will need your Salesforce account information to add an instance.",
  "image":"elements/provider_sfdc.png",
  "active":true,
  "deleted":false,
  "typeOauth":true,
  "trialAccount":false,
  "signupURL":"https://developer.salesforce.com/en/signup",
  "configuration":[  ],
  "defaultTransformations":[  ],
  "resources":[  ],
  "objects":[  ],
  "models":[  ],
  "transformationsEnabled":true,
  "bulkDownloadEnabled":true,
  "bulkUploadEnabled":true,
  "cloneable":true,
  "extendable":true,
  "beta":false,
  "authentication":{  },
  "hooks":[  ],
  "extended":false,
  "hub":"crm",
  "protocolType":"http",
  "parameters":[  ],
  "private":false
}

List Authenticated Connector Instances of a Specific Connector

GET /elements/{keyOrId}/instances

Retrieve all authenticated connector instances of an connector specified by connector key or connector id.

Path Parameters

keyOrIdThe connector key is a unique alphanumeric identifier for the connector, while the connector id is a unique numeric identifier for the connector. Replace keyOrId with either identifier.

Response Fields

The table below shows an abbreviated list of response fields.

idThe connector instance id is a unique numeric identifier for the authenticated connector instance.
name
tokenThe connector instance token returned upon authenticating a connector instance. You must include the connector instance token in the Authorization header of requests to the connector instance.
elementInformation about the connector.
configurationObject containing the configuration of the connector.
eventsEnabled
Indicates whether events are configured for the instance.
userAn object containing details about the user.

Example Request

curl -X GET \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements/23/instances \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response


{  
  "id":436470,
  "name":"Instance Name",
  "token":"+s9zKQa+1EQB9BPfVR1WqaPJfg9UQFwMxeHh+ZcXDiE=",
  "element":{  },
  "tags":[  ],
  "valid":true,
  "disabled":false,
  "configuration":{  },
  "eventsEnabled":false,
  "externalAuthentication":"none",
  "user":{  }
}

Create a Connector Instance

POST /elements/{keyOrId}/instances

Create a new authenticated connector instance specified by connector key or connector id.

Alternatively, you can create an connector instance with a POST /instances request.

Path Parameters

keyOrIdThe connector key is a unique alphanumeric identifier for the connector, while the connector id is a unique numeric identifier for the connector. Replace keyOrId with either identifier.

Request Body Parameters

The body parameters differ based on the authentication type and parameters required by each individual connector. For specific requirements, see the Authenticate or Create Instance section in the documentation for a specific connector.  We've provided some default parameters below for our two most common authentication types: Basic and OAuth 2.0.

Basic Authentication Default Parameters

usernameThe user name needed to authenticate a connector instance with Basic authentication. See the Connector Documentation's Setup section to identify what value at the provider is used as the username.
passwordThe password needed to authenticate a connector instance with Basic authentication. See the Connector Documentation's Setup section to identify what value at the provider is used as the password.
tagsUser-defined tags to further identify or categorize the connector instance.
nameThe display name of the authenticated connector instance.

OAuth 2.0 Authentication Default Parameters

providerData.codeThe authorization grant code returned from the API provider in an OAuth 2.0 authentication workflow. SAP Cloud Platform Open Connectors uses the code to retrieve the OAuth access and refresh tokens from the endpoint.
oauth.api.keyThe API key or client ID obtained by registering your app with the provider. See the Connector Documentation's Setup section to identify what value at the provider is used as the API key.
oauth.api.secretThe API or client secret obtained by registering your app with the API provider. See the Connector Documentation's Setup section to identify what value at the provider is used as the API secret.
oauth.callback.urlThe URL where the API provider returns the authorization grant code and also where a user returns after they authorize access.
tagsUser-defined tags to further identify or categorize the connector instance.
nameThe display name of the authenticated connector instance.

Response Fields

The table below shows an abbreviated list of response fields.

idThe connector instance id is a unique numeric identifier for the authenticated connector instance.
nameThe display name of the authenticated connector instance.
createdDateThe date and time of the initial authentication of the the connector instance.
tokenThe connector instance token returned upon authenticating a connector instance. You must include the connector instance token in the Authorization header of requests to the connector instance.
elementInformation about the connector.
configurationObject containing the configuration of the connector.
eventsEnabledIndicates whether events are configured for the instance.
userAn object containing details about the user.

Example Request

The following example requests represent generic requests using Basic and OAuth 2.0 authentication. 

Basic Authentication Example Request

curl -X POST \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements/insightly/instances \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \
  -d '{
  "configuration": {
    "username": "claudeelements",
    "password": "password"
  },
  "tags": [
    "Docs"
  ],
  "name": "Element Instance Name"
}'

OAuth 2.0 Authentication Example Request


curl -X POST \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/elements/onedrivev2/instances \
  -H 'Authorization: User zn96SWr/RjPPWztl+oQcFkT0mbKPpW7hEvPkYcRy6xM=, Organization 4c193728a11e2d03025e29992948b12c' \
  -H 'Content-Type: application/json' \
  -d '{
  "providerData":{  
    "code":"WCT3Ny3QRbA6HDXY "
  },
  "configuration":{  
    "oauth.api.key": "Rand0MAP1-key",
    "oauth.api.secret":"fak3AP1-s3Cr3t",
    "oauth.callback.url":"https://mycoolapp.com"
  },
  "tags":[  
    "Docs"
  ],
  "name":"Element Instance Name"
}
'

Example Response


{  
  "id":477858,
  "name":"New Element",
  "createdDate":"2018-04-11T18:25:46Z",
  "token":"s1GKjbAO37W1UNsBd4GI80RmUPXk/nzTPFmLKwL1Tws=",
  "element":{  },
  "elementId":5993,
  "tags":[  ],
  "provisionInteractions":[  ],
  "valid":true,
  "disabled":false,
  "maxCacheSize":0,
  "cacheTimeToLive":0,
  "configuration":{  },
  "eventsEnabled":false,
  "traceLoggingEnabled":false,
  "cachingEnabled":false,
  "externalAuthentication":"none",
  "user":{  }
}