Version 22.0.8486

• Authentication
  • cURL
  • Postman
  • JavaScript/JQuery
• Response Format
  • Properties
• Errors
• Data Types

CData Connect provides a full-featured API that allows any REST-compatible application or client capable of creating HTTP requests to query data, perform batch operations, and execute stored procedures in connected data sources. The top API is based on a JSON-formatted API.

All operations in the API are described relative to the CData Connect API base URL, which is the root URL of the application followed by rest.rsc/. For example, if the application is hosted at http://myconnectserver:8080/, then the root URL of the REST API is http://myconnectserver:8080/rest.rsc/

Authentication

All requests to the CData Connect API must be properly authenticated using Basic Authentication. To authenticate a request, pass a username and auth token in the Authorization header of the request. See Users for more information on how to create users and authentication tokens.

You can also authenticate with the API by adding the HTTP header x-cdata-authtoken with the desired Auth Token as part of the HTTP request, as shown below:

GET https://myconnectserver/rest.rsc/schemas

HTTP HEADERS
Accept: application/json
x-cdata-authtoken: MY_AUTH_TOKEN

Below are some examples of how to connect to the REST API using popular HTTP clients.

cURL

One of the simplest ways to retrieve REST data is using the cURL command line tool. The example below shows a cURL command that uses x-cdata-authtoken for authentication:

curl --header "x-cdata-authtoken: my_auth_token" "https://myconnectserver/rest.rsc/My_resource" 

cURL returns the REST response directly to standard output.

Postman

Postman is an API testing utility tool that can easily connect to CData Connect’s REST API. To connect to a resource exposed in this API, set the following settings:

1. Set the HTTP operation to GET.
2. Set the request URL the API base URL followed by the resource. For example, https://myconnectserver/rest.rsc/my_resource.
3. In the Authorization tab, set the Auth type to Basic Auth.
4. Set the Username and password to the username and Auth Token from the Users tab.
5. Click Send to submit the request.

Postman displays the results in the Response section of its interface.

JavaScript/JQuery

JavaScript allows you to retrieve data from a REST source in a web page. The example below shows how to retrieve data from a Connect REST entity:

$.get("https://myconnectserver/rest.rsc/schemas/", 
	{ "@authtoken": "MY_AUTH_TOKEN" }, 
	function(data) {
  $("#result").html(JSON.stringify(data));
});

Response Format

Operations in the CData Connect 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 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 will only contain 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 will still 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.