API Overview

...

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 FormatFormat

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

Elements in square brackets [brackets] are are optional.

Element Description Example

<http/https>

HTTP protocol identifier. The protocol should be https in a production environment.

https

<my_server>

Name of the

D s node

myapp.example.com

<port_number>

Port number over which you access the

D s platform

. By default, this value is 3005.

3005

<version>

API version number.

Info
NOTE: Unless stated otherwise, the versions for all API endpoints is `v4`.

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 <endpoint> and the [resource_id].

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.

...

Parameter lists are consistently enveloped in the following manner:
Code Block
{ "data": [ { ... } ] }
Field names are in in camelCase and are consistent with the resource name in the URL or with the the embed URL parameter.

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

...

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

Info
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/people`
Create	`POST`	`/v4/connections`
Read	`GET`	`/v4/people/1`	`1` = internal user Id
	`GET`	`/v4/connections/10`	`10` = internal connection Id
	`GET`	`/v4/people/1/flows`
List	`GET`	`/v4/people`
List	`GET`	`/v4/connections`
Update	`PATCH`	`/v4/people/1`	Partial replacement
	`PATCH`	`/v4/connections/10`	Partial replacement
	`PUT`	`/v4/people/1`	Full replacement
	`PUT`	`/v4/connections/10`	Full replacement
Delete	`DELETE`	`/v4/people/1`
Delete	`DELETE`	`/v4/connections/10`

...

An association can be referenced using the above URL structuring or by applying the embed query 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:

Code Block
https:/myapp.example.com//v4/jobGroups/1?embed=jobs

...

Code Block

{
    "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<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 value of the association is always included in the response.

...

Info
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

Authentication

Each call to an API endpoint must include authentication credentials for a user with access to the requested objects. See API Authentication.

...

Info

NOTE: API versioning is not synchronized to specific releases of

D s product

. APIs are designed to be backward compatible.

Warning

In the next release of

D s product

product	ee

after Release 6.0, the The v3 endpoints are scheduled to be deprecated. You should move to v4 endpoints at this time. For more information, see API Migration to v4.

...

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:

Info
NOTE: 5xx status codes may be generated by the server.

HTTP Status Code (client errors)	Notes
400 Bad Request	Potential reasons: Resource doesn't exist. Request is incorrectly formatted. Request contains invalid values.
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 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.

...

Info
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.

Page tree

Versions Compared

Old Version 2

New Version Current

Key