Send Requests

Review the following information before sending requests using the Data Transforms REST API.

URL Structure

Here's the URL structure for the requests:

https://<host-url>/<context-path>/<resource-path>

Where host-url is your Data Transforms host URL (see Quick Start), and context-path is /dt-rest/v2.

REST Basics and Resource Identifier Conventions

The Data Transforms REST API follows standard REST principles. The API models resources (for example projects, workflows, dataflows) and uses standard HTTP methods to operate on them:

  • GET — retrieve representations of resources or collections (safe, does not modify server state).
  • POST — create a new resource or trigger an action (non-idempotent by default).
  • PUT — replace or update a resource (idempotent: repeating the same PUT yields the same result).
  • DELETE — remove a resource.

For any endpoint that creates a resource (POST) or updates a resource (PUT), the service returns a representation that includes the resource identifier (the field named objectId, designObjectId or the resource id like projecId, jobId, and so on in responses). For example:

The endpoint /dt-rest/v2/jobs/submit creates and executes a job based on the request payload. For example, a payload like this:
{
    “action":"RUN",
    "objectType":"DATAFLOW",
    "objectId":"objectId_example",
    "objectName":"objectName_example",
    "synchronous":true,
    "ignorePreviousRunningJob":true,
    "jobName":"jobName_example",
    "jobVariables":{}
}

would return a response such as:

{
    "status": "WAITING",
    "jobName": "project_objectName_example",
    "jobNumber": 1152,
    "jobId": "333f43d5-dcac-417d-947d-aa2787bd7333",
    "executionStatistics": {
        "timeZone": "UTC",
        "serverTimeZone": "UTC"
    },
    "recordStatistics": {
        "insertCount": 0,
        "updateCount": 0,
        "deleteCount": 0,
        "recordCount": 0,
        "errorCount": 0
    },
    "synchronous": true,
    "jobVariables": {}
}

Idempotency and Safe Operations

  • POST is normally not idempotent. Do not retry blindly.
  • PUT is idempotent. Repeating a successful PUT with the same payload should produce the same end-state.

Pagination and fields

For list operations, the API supports standard pagination (for example page/limit or offset/limit) and a fields query parameter to return a summarized projection. Each returned item will still include an objectId.

Supported Operations

Perform basic CRUD operations (create, read, update, and delete) on your Data Transforms service using standard HTTP request methods.

HTTP Method Description
GET Retrieve information about the resource.
POST Create a resource or execute a job for a resource.
PUT Update a resource.
DELETE Delete a resource.

Media Types

The application/json media type is supported by the Data Transforms REST API:

Supported Headers

The Data Transforms REST API supports the following headers that may be passed in the header section of the HTTP request or response.

Header Description Example
Accept Media type of the body of the response. Accept application/json
Content-Type Media type of the body of the request. Required for POST and PUT requests. Content-Type: application/json
Authorization Token for the particular session authorization: Bearer <Token value>

Working with Variables

Refer to the MY_VAR variable in your objects as follows:

  • #MY_PROJECT_CODE.MY_VAR: This is the preferred syntax. It allows you to use variables by explicitly stating the project that contains the variable. It prevents ambiguity when two variables with the same name exist, for example, at global and project level. The value of the variable is substituted at runtime.
  • #MY_VAR: With this syntax, the variable must be in the same project as the object referring to it. To avoid ambiguity, consider using fully qualified syntax by prefixing the variable name with the project code.
  • #GLOBAL.MY_VAR: This syntax allows you to refer to a global variable.