• Authentication
• Workspaces
• Response Format
  • Properties
• Errors
• Data Types

CData Connect Cloud provides a full-featured API that allows any REST-compatible application or client tool capable of creating HTTP requests to query data, perform batch operations, and execute stored procedures across all data sources configured in your account. This API is based on a JSON-formatted API. All operations in the API are described relative to the CData Connect Cloud API’s base URL:

https://cloud.cdata.com/api

Authentication

All requests to the CData Connect Cloud API must be properly authenticated using Basic Authentication. To authenticate a request, pass the base64-encoded login credentials of a registered user in the Authorization header of the request. Follow this guidance when passing the credentials:

• The username is the email address of the user, e.g. user@cdata.com.
• The password is a Personal Access Token (PAT) that you generate from the Settings page.
• If your application or service does not automatically base64-encode the string, follow these steps to encode it manually:
  • Separate the username and PAT with a colon, e.g. user@cdata.com:token.
  • Use base64 to encode the colon-separated string.

The following is an example of a curl command that calls the API to return results from a Salesforce Account table:

curl -X POST https://cloud.cdata.com/api/query
   -H "Content-Type: application/json"
   -d '{"query":"SELECT * FROM Salesforce1.Salesforce.Account LIMIT 10"}'
   --user "user@cdata.com:123456789abcdefghijklmnopqrstuvwxyz" 

Since curl automatically base64-encodes basic authentication credentials, it is not necessary to manually perform this encoding before sending the request.

Workspaces

To query a workspace, add a URL parameter to the REST API URL named “workspace”. Set this to the name of the workspace you want to query. This works with both the GET operation on the metadata endpoint, as well as the POST operation on the query and batch endpoints. Note that the /exec endpoint does not support workspaces.

Response Format

Operations in the CData Connect Cloud API share a common response format which, depending on the operation, may include:

• One or more result sets with:
  • Result column metadata
  • Row values, if any
  • Affected row count
• Output and return parameters (for applicable stored procedure executions)
• Any error that may have occurred prior to, during, or after request processing

The response objects returned by the API contain one or more of the top-level properties shown below:

{
  "results": [
    {
      "schema": [
        {
          "ordinal": <int>,
          "catalogName": "<string>",
          "schemaName": "<string>",
          "tableName": "<string>",
          "columnName": "<string>",
          "columnLabel": "<string>",
          "dataType": <int>,
          "dataTypeName": "<string>",
          "length": <int>,
          "precision": <int>,
          "scale": <int>,
          "nullable": <bool>
        },
        ...
      ],
      "rows": [
        [<any>, <any>, ...],
        ...
      ],
      "affectedRows": <int>,
    },
    ...
  ],
  "parameters": {
    "@p1": { "dataType": <int>, "direction": <int>, "value": <any> }
    ...
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Properties

Errors

When CData Connect Cloud receives an API request, it validates it, executes it, and then serializes and streams back the results as they arrive. If an error occurs prior to or during execution, the response object only contains error information. However, it is also possible for errors to occur after a query’s results have started being returned. In such cases, the response object may contain both a partial result as well as error information stating that the result is incomplete.

Since the HTTP status code is returned before the body, incomplete responses have a 200 OK status. As such, it’s important that you always check for the presence of error information in the response rather than relying solely on the HTTP status code.

Data Types

The following table shows the valid values for the dataType property in the Result Set Serialization.