Changes to the APIs

Beginning in this release, the settings in a writesettings object are no longer validated as part of job execution for scheduled and API-based jobs. A writesettings object defines the file-based output for a job.

This feature is enabled by default. A workspace administrator can disable the feature if needed.

For more information, see Workspace Settings Page.

For some API endpoints that are heavily used or critical to the success use of the platform, rate limiting has been applied. API rate limiting sets the maximum number of requests that are accepted by an endpoint within a specified period of time. For example, you may be prevented from sending more than 50 requests to start a job or plan run within a minute.

See: https://api.trifacta.com/ee/9.7/index.html#section/Overview/Rate-limiting

The following endpoint for transferring assets between users has been removed from the product:

/v4/people/{to-userid:}/assetTransfer/{from-userid:}

The above endpoint no longer works.

In a previous release, this endpoint was replaced by an improved method of asset transfer. For more information, see "Asset transfer API using email addresses" below.

The following endpoints have been deprecated:

/v4/connections/vendors
/v4/connections/credentialTypes
/v4/connections/:id/publish/info
/v4/connections/:id/import/info

These endpoints were scheduled for deprecation in Release 8.2 and are not widely used.

/v4/connectormetadata/:connectorname

Beginning in Release 8.1, you can customize aspects of each relational connection type available in your product edition through a set of APIs. Some terms:

/v4/connectorMetadata/:connectorId/defaults

GET

/v4/connectorMetadata/:connectorId/

GET

/v4/connectorMetadata/:connectorId/overrides

GET

/v4/connectorMetadata/:connectorId/overrides

POST

/v4/connectorMetadata/:connectorId/overrides

DELETE

In prior releases, API requests to the /v4/awsConfig endpoint using the PUT method could receive the following error:

{
"exception":
{ "name": "ApiValidationFailed", "message": "Message does not adhere to API specification", "details": "'credentialProvider' field in request body must not be null" }}

The credentialProvider field is not required, and this requirement has been removed from the endpoint. https://api.trifacta.com/ee/9.7/index.html#operation/updateAwsConfig

In prior releases, the /v4/awsConfigs endpoint supported the use of a PUT method to modify AWS configuration objects.

This endpoint-method combination has been deprecated. The new PATCH method is the following:

{
    "role":"<my_iam_role_object_3>"
}

https://api.trifacta.com/ee/9.7/index.html#operation/updateAwsConfig

For more information on configuring AWS access objects, see API Task - Manage AWS Configurations.

Beginning in Release 7.5, the API has been enhanced to allow insertion of a user's email address as part of the request body. Below is an example request:

    "data": [
        {
            "email": "user@example.com",
            "role": "collaborator",
            "policy": "flow_editor"
        }
    ]
}

If the above returns a 201 - Success status message, then user@example.com has been given the role of collaborator, which uses the flow_editor policy, for flowId 402.

https://api.trifacta.com/ee/9.7/index.html#operation/shareFlow

Beginning in Release 7.1, API reference documentation is available directly from the Trifacta Application. From the menu bar, select Resources menu > API documentation.

Key features:

More content and features will be added to this new capability of the next few releases.

Task documentation is still available in the product documentation. For more information on these tasks, see API Reference.

Release 7.1 introduces authorization, which provides finer-grained access controls to user-defined objects in the platform. For more information, see Changes to User Management.

As a result of authorization, the following changes have been applied to the listed API endpoints.

"policyTag": "connection_viewer",

"policyTag": "connection_viewer",
"workspaceAdmin": false,
"isCreatedBy": true,

{
    "data": [
        {
            "id": 14,
            ....
            "associatedPeople": {
                "data": [
                    {
                        "id": 1,
                        ...
                        "authorizationPermission": {
                            "policyName": null,
                            "policyTag": "workspace_admin",
                            "resourceOperationList": [
                                {
                                    "operations": [
                                        "execute",
                                        "delete",
                                        "update",
                                        "read",
                                        "create",
                                        "share"
                                    ],
                                    "policyTag": "plan_author",
                                    "resourceType": "plan"
                                },
                                {
                                    "operations": [
                                        "execute",
                                        "delete",
                                        "update",
                                        "read",
                                        "create",
                                        "share"
                                    ],
                                    "policyTag": "flow_author",
                                    "resourceType": "flow"
                                },

{
    "data": [
        {
            "id": 29,
            ....
           "maximalPrivileges": [
                {
                    "operations": [
                        "delete",
                        "update",
                        "read",
                        "create",
                        "share"
                    ],
                    "policyTag": "connection_author",
                    "resourceType": "connection"
                },
                {
                    "operations": [
                        "execute",
                        "delete",
                        "update",
                        "read",
                        "create",
                        "share"
                    ],
                    "policyTag": "plan_author",
                    "resourceType": "plan"
                },
                {
                    "operations": [
                        "execute",
                        "delete",
                        "update",
                        "read",
                        "create",
                        "share"
                    ],
                    "policyTag": "flow_author",
                    "resourceType": "flow"
                }
            ],
            "authorizationRoles": [
                {
                    "policyId": 13,
                    "name": "default",
                    "tag": null,
                    "workspaceId": 1,
                    "createdAt": "2020-04-22T07:50:04.502+0000",
                    "updatedAt": "2020-04-22T07:50:04.502+0000",
                    "resourceOperations": [
                        {
                            "operations": [
                                "execute",
                                "delete",
                                "update",
                                "read",
                                "create",
                                "share"
                            ],
                            "policyTag": "plan_author",
                            "resourceType": "plan"
                        },
                        {
                            "operations": [
                                "execute",
                                "delete",
                                "update",
                                "read",
                                "create",
                                "share"
                            ],
                            "policyTag": "flow_author",
                            "resourceType": "flow"
                        },
                        {
                            "operations": [
                                "delete",
                                "update",
                                "read",
                                "create",
                                "share"
                            ],
                            "policyTag": "connection_author",
                            "resourceType": "connection"
                        }
                    ]
                }
            ],

Beginning in Release 7.1, the structure of a Salesforce connection object has been changed. In prior releases, a Salesforce connection could not be shared without also sharing credentials. These changes allow a Salesforce connection to be shared without requiring the sharing of credentials.

Prior to Release 7.1, when creating a Salesforce connection using the APIs, the /v4/connections POST method required the insertion of a Salesforce security token as part of the params section of the request:

{
  "vendor": "salesforce",
  "vendorName": "salesforce",
  "type": "jdbc",
  "credentialType": "basic",
  "ssl": true,
  "name": "Salesforce",
  "description": "example_salesforce_connection",
  "disableTypeInference": true,
  "isGlobal": true,
  "credentialsShared": true,
  "host": "salesforce.example.com",
  "params": {
    "servername": "myServer",
    "securityToken": "string"
  },
  "credentials": [
    {
      "username": "string",
      "password": "string"
    }
  ]
}

Beginning in Release 7.1, the following changes have been applied to this request structure:

{
  "vendor": "salesforce",
  "vendorName": "salesforce",
  "type": "jdbc",
  "credentialType": "securityToken",
  "ssl": true,
  "name": "Salesforce",
  "description": "example_salesforce_connection",
  "disableTypeInference": true,
  "isGlobal": true,
  "credentialsShared": true,
  "host": "salesforce.example.com",
  "params": {
    "servername": "myServer"
  },
  "credentials": [
    {
      "username": "string",
      "password": "string",
      "securityToken": "string"
    }
  ]
}

For more information:

You can now apply overrides to your file-based data sources when you run a job using the APIs. See API Task - Run Job.

The v3 version of the API endpoints are no longer available in the platform.

You must use the v4 versions. See API Reference.

In Release 6.8 and earlier, you could create an imported dataset from a file-based source using a request like the following:

{
  "path": "/tri-hdfs/uploads/1/4aee9852-cf92-47a8-8c6a-9ff2adeb3b4a/POS-r02.txt",
  "type": "hdfs",
  "bucket": null,
  "name": "POS-r02b.txt",
  "description": "POS-r02 - copy"
}

Beginning in this release, you can specify the source using a single uri value:

{
  "uri": "hdfs:///tri-hdfs/uploads/1/4aee9852-cf92-47a8-8c6a-9ff2adeb3b4a/POS-r02.txt",
  "name": "POS-r02b.txt",
  "description": "POS-r02 - copy"
}

For more information, see

https://api.trifacta.com/ee/9.7/index.html#operation/createImportedDataset

Prior to Release 7.0, the platform supported the ability to retrieve awsRole objects based on awsRoleId value.

In Release 7.0 and later, this endpoint has been disabled in the product.

Prior to Release 7.0, the request to create a connection looked liked the following:

{
    "connectParams": {
        "vendor": "sqlserver",
        "vendorName": "sqlserver",
        "host": "sqlserver.example.com",
        "port": "1433"
    },
    "host": "sqlserver.example.com",
    "port": 1433,
    "vendor": "sqlserver",
    "params": {
        "connectStrOpts": ""
    },
    "ssl": false,
    "vendorName": "sqlserver",
    "name": "sqlserver_test2",
    "description": "",
    "type": "jdbc",
    "isGlobal": false,
    "credentialType": "basic",
    "credentialsShared": true,
    "disableTypeInference": false,
    "credentials": [
        {
            "username": "<username>",
            "password": "<password>"
        }
    ]
}

In the above, the connectParams information is duplicated elsewhere in the request.

Beginning in Release 7.0, the connectParams elements of the Connections endpoint have been removed.

The above request now looks like the following:

{
    "host": "sqlserver.example.com",
    "port": 1433,
    "vendor": "sqlserver",
    "params": {
        "connectStrOpts": ""
    },
    "ssl": false,
    "vendorName": "sqlserver",
    "name": "sqlserver_test2",
    "description": "",
    "type": "jdbc",
    "isGlobal": false,
    "credentialType": "basic",
    "credentialsShared": true,
    "disableTypeInference": false,
    "credentials": [
        {
            "username": "<username>",
            "password": "<password>"
        }
    ]
}

Required changes:

For more information, see

https://api.trifacta.com/ee/9.7/index.html#operation/getConnection

After you have run a job, you can publish the results from the job using the following endpoint:

/v4/jobGroups/<id>/publish

Prior to Release 7.0, the request to submit to the endpoint looked like the following:

{
  "connection": {
    "id": 1
  },
  "path": ["default"],
  "table": "test_table",
  "action": "create",
  "inputFormat": "pqt",
  "flowNodeId": 27
}

However, the flowNodeId value is not necessary, as it can be inferred from the id value that is part of the endpoint URI.

Beginning in Release 7.0, the request no longer requires the flowNodeId value:

{
  "connection": {
    "id": 1
  },
  "path": ["default"],
  "table": "test_table",
  "action": "create",
  "inputFormat": "pqt"
}

For more information, see

https://api.trifacta.com/ee/9.7/index.html#operation/publishJobGroup

In Release 6.8 and earlier, the supported format for WASB URIs was the following:

wasbs://blobhost.blob.core.windows.net/container/path/to/file.csv

This format was not an Azure standard. Beginning in Release 7.0, the following standards-based format is supported:

wasbs://container@blobhost.blob.core.windows.net/path/to/file.csv

In Release 6.8 and earlier, when saving a Databricks Personal Access Token, the response looked like the following:

Beginning in Release 7.0, the response looks like the following:

{
  "message": "Databricks Personal Access Token has been stored for user <user_email>"
}

For more information, see

https://api.trifacta.com/ee/9.7/index.html#operation/saveDatabricksAccessToken

In Release 6.8 and earlier, the following issues appeared in the documentation for the awsRoles object. These issues have been corrected in this release:

Inadequate permissions:

The POST and PUT methods for the awsRoles endpoint require either of the following user permissions:

Optional workspaceid/personid attributes:

For the POST and PUT methods for the awsRoles endpoint, you can optionally assign the role to a workspace or person.

See

https://api.trifacta.com/ee/9.7/index.html#operation/createAwsRole

See

https://api.trifacta.com/ee/9.7/index.html#operation/updateAwsRole

Before disabling or deleting a user's account, an admin may wish to transfer the user's assets to the ownership of a different user. For more information on how to transfer all assets via API, see https://api.trifacta.com/ee/9.7/index.html#operation/transferAssets

Through the APIs, you can now apply overrides to relational sources and targets during job execution or deployment import.

Release 6.8 introduces a new version of the flow object definition. This new version will support cross-product and cross-version import and export of flows in the future. For more information see Changes to the Object Model.

Beginning in Release 6.8, you can export and import macro definitions via API.

For this endpoint:

/v4/connections/<cid>/permissions/

where:

The request payload format has changed.

Before Release 6.4, the request format was as follows:

[
  {
    "personId": 3,
    "role": "readOnly"
  }
]

Beginning in Release 6.4, the request format is as follows:

{
  "data": [
    {
      "person": {
        "id": 3
      },
      "role": "readOnly"
    }
  ]
}

For more information, see https://api.trifacta.com/ee/9.7/index.html#operation/createConnectionPermission

To assist in migration from the command-line interface to using the APIs, a v4 version of an API endpoint has been made available to allow for administrators to generate password reset codes.

In Release 6.0, the awsConfig object was introduced to enable the assignment of AWS configurations to individual users (per-user auth) via API. This version of the awsConfig object supported a mapping of a single IAM role to an awsConfig object.

Beginning in Release 6.4, per-user authentication now supports mapping of multiple possible IAM roles to an individual user's configuration. To enable this one-to-many mapping, the awsRoles object was introduced.

Changes to awsConfig object:

Beginning in Release 6.4, you can create, edit, and delete awsRoles objects, which can be used to map an AWS IAM role ARN to a specified AWSConfig object. You can map multiple awsRoles to a single awsConfig.

For more information, see API Task - Manage AWS Configurations.

Beginning in Release 6.3, you can assign an AWSConfig object to a user when you create the object. This shortcut reduces the number of REST calls that you need to make.

Prior to Release 6.3, AWSConfig objects were assigned through the following endpoint. Example:

/v4/people/2/awsConfigs/6

See API Task - Manage AWS Configurations.

In Release 6.0 - Release 6.0.2, the online and PDF versions of the documentation referenced the following endpoint: API JobGroups Get Status v4. According to the docs, this endpoint was triggered in this manner:

/v4/jobGroups/<id>/status

This endpoint exists in v3 of the API endpoints. It does not exist in v4.

Instead, you should monitor the status field for the base GET endpoint for jobGroups. For more information, see https://api.trifacta.com/ee/9.7/index.html#operation/getJobGroup

In Release 6.0, the v3 API endpoints are supported.

You must migrate to using the v4 API endpoints before upgrading to the next release after Release 6.0.

Each request to the API endpoints of the Designer Cloud Powered by Trifacta platform requires submission of authentication information. In Release 5.1 and earlier:

Beginning in Release 5.9, API users can manage authentication using access tokens. These tokens obscure any personally identifiable information and represent a standards-based method of secure authentication.

The basic process works in the following manner:

Access tokens can be generated via API or the Trifacta Application.

For more information on API authentication methods, see https://api.trifacta.com/ee/9.7/index.html#section/Authentication

Release 5.0 signals the introduction of version 4 of the REST APIs.

v4 conventions

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

You can create connections of these types via API:

In Release 4.1.1 and earlier, the WrangledDataset endpoints enabled creation, modification, and deletion of a wrangled dataset object, which also created the associated recipe object.

In Release 4.2, wrangled datasets have been removed from the application interface. However, the WrangledDataset API endpoints remain, although they now apply to the recipe directly.

The following endpoints and methods are still available:

For more information, see Changes to the Object Model.