API Overview

To enable programmatic control over its objects, the Designer Cloud Powered by Trifacta® platform supports a range of REST API endpoints across the objects in the platform. This section provides an overview of the API design, methods, and supported use cases.

Supported operations:

• Connections: Get information about connections
• Datasets: Create, list, update, and delete operations on datasets
  • Swap datasets
• Jobs and Results:
  • Launch job
  • Get job status
  • Publish job results
  • Create dataset from results
• Get profile metadata:
  • Quality bar status
  • Schema (column names and types)
• Users: Create, list, delete

Uses:

• Can be used for automation of resource management for end-to-end workflow
• Can be used to integrate wrangling experience in third-party application
• See Use Cases below.

Design Overview

URL Format

<http/https>://<my_server>:<port_number>/<version>/<endpoint>/[resource_id]/[association][?args]

Elements in square brackets [brackets] are optional. 

Naming Conventions

• Resource names are plural and expressed in camelCase.
• Resource names are consistent between main URL and URL parameter.

v4 conventions

The following conventions apply to v4 and later versions of the APIs:

• Parameter lists are consistently enveloped in the following manner:

  { "data": [
      {
        ...
      }
    ]
  }

• Field names are in camelCase and are consistent with the resource name in the URL or with the embed URL parameter.

• From early API versions, foreign keys have been replaced with identifiers like the following:

  v3 and earlier	v4 and later
  "createdBy": 1,	"creator": { "id": 1 },
  "updatedBy": 2,	"updater": { "id": 2 },

Operations and Methods

Support for basic CRUD (Create, Read, Update, and Delete) operations across most platform objects.

Embedding Associations

An association can be referenced using the above URL structuring or by applying the embed query parameter as part of the reference to the specific resource. In the following example, the sub-jobs of a jobGroup are embedded in the response for jobGroup=1:

https:/wrangler.example.com//v4/jobGroups/1?embed=jobs

Example response:

{
    "id": 1,
    "name": null,
    "description": null,
    "ranfrom": "ui",
    "ranfor": "recipe",
    "status": "Complete",
    "profilingEnabled": true,
    "runParameterReferenceDate": "2019-04-23T17:00:56.000Z",
    "createdAt": "2019-04-23T17:00:56.728Z",
    "updatedAt": "2019-04-23T17:01:03.084Z",
    "jobs": {
        "data": [
            {
                "id": 1,
                "executionLanguage": "photon",
                "cpJobId": null,
                "templateLocation": null,
                "createdAt": "2019-04-23T17:00:56.952Z",
                "updatedAt": "2019-04-23T17:01:00.670Z",
                "status": "Complete",
                "jobType": "wrangle",
                "sampleSize": 100,
                "percentComplete": 100,
                "lastHeartbeatAt": "2019-04-23T17:00:58.589Z",
                "creator": {
                    "id": 1
                },
                "jobGroup": {
                    "id": 1
                },
                "errorMessage": null,
                "wrangleScript": null,
                "emrcluster": null
            },
            {
                "id": 2,
                "createdAt": "2019-04-23T17:00:57.034Z",
                "updatedAt": "2019-04-23T17:01:02.642Z",
                "status": "Complete",
                "jobType": "filewriter",
                "sampleSize": 100,
                "percentComplete": 100,
                "lastHeartbeatAt": "2019-04-23T17:01:00.922Z",
                "creator": {
                    "id": 1
                },
                "jobGroup": {
                    "id": 1
                },
                "errorMessage": null,
                "scriptResult": {
                    "id": 1
                },
                "writeSetting": {
                    "id": 2
                }
            },
            {
                "id": 3,
                "createdAt": "2019-04-23T17:00:57.037Z",
                "updatedAt": "2019-04-23T17:01:03.077Z",
                "status": "Complete",
                "jobType": "filewriter",
                "sampleSize": 100,
                "percentComplete": 100,
                "lastHeartbeatAt": "2019-04-23T17:01:00.843Z",
                "creator": {
                    "id": 1
                },
                "jobGroup": {
                    "id": 1
                },
                "errorMessage": null,
                "scriptResult": {
                    "id": 2
                },
                "writeSetting": {
                    "id": 1
                }
            }
        ]
    },
    "workspace": {
        "id": 1
    },
    "creator": {
        "id": 1
    },
    "updater": {
        "id": 1
    },
    "snapshot": {
        "id": 8
    },
    "wrangledDataset": {
        "id": 7
    },
    "flowRun": null
}

The id value of the association is always included in the response. 

Media Type Headers

Authentication

The REST APIs use the same authentication methods as the UI. Each call to an API endpoint must include authentication credentials for a user with access to the requested objects. See API Authentication.

SSL

If SSL has been enabled for the Designer Cloud Powered by Trifacta platform, requests to URL endpoints are automatically redirected to the HTTPS equivalent.

Upload

Single-file upload is supported.

Multi-file upload is not supported.

Versioning and Endpoint Lifecycle

APIs are designed to be backward compatible so that scripts and other tooling built on a previous version of an endpoint remain valid until the previous version has reached end-of-life. Each API is supported across a window of  Designer Cloud Enterprise Edition releases, after which you must reference a newer version of the API.

API endpoint routes support a consistent structuring and do not contain business logic. 

Version information is available at the following endpoint:

<http/https>://<my_server>:<port_number>/<version>/version

For more information, see API Version Support Matrix.

HTTP Status Codes and Errors

The following error codes can apply to any of the above requests:

Caching

When a resource has been cached in the client, the client may set an If-Modified-Since header in HTTP date format on the request. If so:

Use Cases

REST API Tasks

By chaining together sequences of calls to API endpoints, you can create, read, update, and delete objects using identifiers accessible through the returned JSON. For more information, see API Endpoints.

For more information on endpoint workflows, see API Workflows.

UI Integrations

The REST APIs can also be used for integrating the core transformation experience of the Designer Cloud Powered by Trifacta platform into a third-party application. Using a series of URL-based calls, you can retrieve and display specified datasets in the Transformer page, where authenticated users can wrangle datasets controlled by the third-party application. See API - UI Integrations.

About This Documentation

• Unless otherwise noted, the documentation and examples apply to version 4 (v4) of the Designer Cloud Powered by Trifacta platform APIs.
• Examples may require modification to work in your environment.