Contents:
To enable programmatic control over its objects, Designer Cloud Enterprise Edition 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.
Design Overview
URL Format
<http/https>://<my_server>:<port_number>/<version>/<endpoint>/[resource_id]/[association][?args]
Elements in square brackets [brackets]
are optional.
Element | Description | Example |
---|---|---|
<http/https> | HTTP protocol identifier. The protocol should be | https |
<my_server> | Name of the Alteryx node | myapp.example.com |
<port_number> | Port number over which you access the platform. By default, this value is | 3005 |
<version> | API version number. NOTE: Unless stated otherwise, the versions for all API endpoints is | v4 |
<endpoint> | Name of the API endpoint to use. | /connections |
[resource_id] | Internal identifier for the specific resource requested from the endpoint. This value defines the object against which the requested operation is performed. | /10 |
[association] | If applicable, the association identifiers the API endpoint that is requested using the context determined by the Associations can also be referenced by query parameter. See Embedding Associations below. | /jobGroups |
[?args] | In some cases, arguments can be passed to the endpoint in the form of query parameters. | ?arg1=value1&arg2=value2
|
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 theembed
URL parameter.
Foreign keys are represented with identifiers like the following:
"creator": { "id": 1 }, "updater": { "id": 2 },
Operations and Methods
Support for basic CRUD (Create, Read, Update, and Delete) operations across most platform objects.
NOTE: Some of these specific operations may not be supported in the current release. For a complete list, see API Endpoints.
Operation | HTTP Method | Example URL | Notes |
---|---|---|---|
Create | POST | /v4/jobgroups | |
POST | /v4/importedDatasets | ||
Read | GET | /v4/jobgroups/1 | 1 = internal jobgroup Id |
GET | /v4/importedDatasets/10 | 10 = internal imported dataset Id | |
List | GET | /v4/flows | |
GET | /v4/wrangledDatasets | ||
Update | PATCH | /v4/wrangledDatasets/10 | Partial replacement |
PUT | /v4/outputObjects/1 | Partial replacement | |
Delete | DELETE | /v4/importedDatasets/1 | |
DELETE | /v4/outputObjects/10 |
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:/myapp.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": "<running_environment>", "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
NOTE: Some endpoints may accept and return a custom media type. These endpoints are documented.
Action | Header | Required? |
---|---|---|
Client request that expects a response body | request header:Accept: application/json | should include |
Client request that includes a request body | request header:Content-Type: application/json | required |
Server response that includes a response body | response header:Content-Type: application/json | required |
Request identifier
Each request contains a request identifier in the following form:
x-trifacta-request-id: <myRequestId>
The above request header also appears as a header in the response.
NOTE: If you have an issue with a specific request, please include the x-trifacta-request-id
value when you contact Alteryx Support.
Authentication
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 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
NOTE: API versioning is not synchronized to specific releases of Designer Cloud Enterprise Edition. APIs are designed to be backward compatible.
The v3 endpoints are deprecated. You should move to v4 endpoints at this time.
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
Request Method | Request Endpoint | HTTP Status Code (success) |
---|---|---|
POST | /v4/<resource> | 201 Created |
GET | /v4/<resource> | 200 OK |
GET | /v4/<resource>/<id> | 304 Not Modified when client has cached version. See Caching below. |
PATCH | /v4/<resource>/<id> | 200 OK |
PUT | /v4/<resource>/<id> | 200 OK |
DELETE | /v4/<resource>/<id> | 204 No Content |
The following error codes can apply to any of the above requests:
NOTE: 5xx status codes may be generated by the server.
HTTP Status Code (client errors) | Notes |
---|---|
400 Bad Request | Potential reasons:
|
403 Forbidden | Incorrect permissions to access the Resource. |
404 Not Found | Resource cannot be found. |
410 Gone | Resource has been previously deleted. |
415 Unsupported Media Type | Incorrect Accept header. |
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:
General Response | HTTP Status Code |
---|---|
Returns full modified resource | 200 OK |
Returns an empty response for unmodified resource | 304 Not Modified |
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
Applicable API versions
Unless otherwise noted, the documentation and examples apply to latest version of the platform APIs.
API examples
Examples may require modification to work in your environment.
NOTE: Some examples may not be reflective of your environment. Examples may contain references to examples or features not supported in your environment.
- Reference examples are included as part of endpoint documentation. See API Endpoints.
- Usage examples are included in the workflows. See API Workflows.
This page has no comments.