The Aperture Data Studio REST API provides a RESTful interface which can be integrated programmatically with your system without the need to use Aperture Data Studio.

API reference

The full interactive API reference is available in the form of Swagger-UI. This will allow you to test out the resources and get a better understanding of the requests and parameters.

You can access the Swagger-UI at http://<server>/api/docs/index.html. If you have installed Aperture Data Studio locally using the default server port, the URL will be http://localhost:7701/api/docs/index.html.

With our easy to use API you can:

You can use our API to execute a specific Workflow or to list the status of currently running/recently run Workflows.

Execute a Workflow

To execute a specific Workflow, you have to use the external label parameter which is defined in the Workflow properties. The following parameters have to also be supplied:

Parameters Description
externalLabel The external label specified in Workflow properties.

Type: String
versionToExecute Select whether to execute the latest draft or the last published version of the Workflow.

Type: String
Valid options: PreferDraft, PublishedOnly
dependenciesToUse When Functions and Views are used in the Workflow, select whether to execute the latest draft or the last published version of the Workflow.

Type: String
Valid options: PreferDraft, PublishedOnly
refreshSources Determines whether source data should be refreshed before executing the Workflow. Type: Boolean
workflowParameters Defines the Workflow parameter values that will be used in the execution.Type: String
sources Defines the data source that will be used in the execution. Two properties per source are accepted: the Source step's and the Dataset's external label.

The Source step's external label is used to ensure that the correct Source step is configured. The Can supply source when executed option has to be enabled for this Workflow step to make the data source replaceable at Workflow execution.

The Dataset's external label is used to refer to the Dataset which will be used by the Source step when the Workflow is executed. This is only mandatory if the Must be supplied option is enabled in the step. Otherwise, the Workflow will be executed with the default data source. Type: String

Executing a Workflow will return an executionID which you can use to check the status of the job.

Check the status of Jobs

The API allows you to query the status of all recently executed or a specific Job using the executionID.

For each Job, the information returned is the same that's available in the Jobs page in Data Studio:

  • The name of the Workflow
  • Who initiated the Workflow
  • Start and end time
  • Current state (InProgress, Executed, Completed, Failed, Stopped oe Started)
  • Details for each step completed within that Workflow

Two audit methods exist: to report information on user sessions and to report all audit events.

Report user sessions

The /sessions endpoint returns a list of all user sessions, within a specified number of seconds or up to a record limit.

The returned list contains:

  • The user ID and Name
  • Start and end date/time of the sessions
  • The environment which was accessed

Report all audit events

The /events endpoint returns a more detailed list of all events recorded by the system. Each event has a date and type and is associated with a user and specific session ID.

You can monitor the state of health of the system and for diagnostic purposes. The metrics endpoints return both Java and application metrics for the entire system across all Environments:

  • The Java metrics track the application JVM resource consumption in terms of process CPU usage, memory usage, active thread count and the garbage collection process.
  • The application metrics (e.g. number of active user sessions, response time to load specific UI pages) can be used to measure and monitor the performance of Data Studio over time.

You can use the REST API to create and delete Datasets.

Create a Dataset

When creating a Dataset, the following parameters can be supplied:

Parameters Description
datasetName The name of the Dataset to be uploaded.

Type: String
externalLabel (Optional) The external label of the Dataset to be uploaded.

Type: String
space The Space that the Dataset will be uploaded to.

Type: String
Default value: Your space
filepath The file path of the cloud storage that the Dataset will be uploaded from.
Type: String
autotag (Optional) If 'True', enables the auto-tagging option for the Dataset to be uploaded.

Type: Boolean
Default value: True
Valid options: True, False
type The external system type (as defined in Data Studio) used to upload the Dataset.

Type: String
Default value: Amazon_S3
name The external system name (as defined in Data Studio) used to upload the Dataset.
Type: String
credentialName The external system credential name (as defined in Data Studio) used to upload the Dataset.
Type: String

Creating a Dataset will return a statusID which you can use to check the creation status of the Dataset.

Delete a Dataset

To delete a required Dataset from Data Studio, you have to use the combination of spaceId or space external label and datasetId or dataset external label. Once deleted, a successful operation with no content will be returned.

Query the creation status of a Dataset

Some Datasets are large and can take a significant amount of time to be created in Data Studio when importing from an external source. After using the REST API to create a Dataset, you can query the creation status to determine whether the operation completed successfully.

Aperture Data Studio provides this ability to check the Dataset creation progress and status via an HTTP GET endpoint, using the statusId as the path parameter.

When querying the creation status of a Dataset, the following response information can be expected:

Response information Description
status The current overall creation status of the Dataset when the query was executed.
Possible statuses are: Queued, Initialize, CreateDataset, AutoTagging, Loading, Created, and Error.
The creation status transitions in the following order:
Queued > Initialize > CreateDataset > (If configured) AutoTagging > Loading > Created.
Should an error occur at any point of creation process, the status returned is Error.
statusId The ID of this status response.
tagInfo The column tagging information for the Dataset. If auto-tag is enabled, a tagInfo object is returned, otherwise returns null.
endTime The time of completion of the Dataset creation.
startTime The time when the Dataset creation began.
datasetInfo Contains details about the Dataset, such as rowCount, datasetUuid, and externalLabel. If overall status successfully reaches Created, a datasetInfo object is returned with the relevant information. Returns null if Dataset creation was unsuccessful.
errorMessage Contains details about Dataset creation failure, such as reason and details if Dataset creation was unsuccessful. Returns null if Dataset creation was successful.
phasesProgress Contains details about the Dataset creation tasks, such as progressPercentage, status, and durationMs. durationMs refers to the elapsed time for the phase in milliseconds. A phase is a stage in the Dataset creation process as described in status above.

The REST API can be used to modify the sharing options of views, as well as include views into other spaces.

Retrieve sharing details for a view

Return sharing details for a view, including the sharing mode (global/specific spaces/none) and the spaces it is shared with.

Parameters Description
spaceId The ID or external label of the space the view belongs to.

Type: String
viewId The ID of the view to be returned.

Type: String

Update view sharing settings

Update the sharing settings of a view, including changing the sharing mode or adding/removing spaces that the view can be shared with.

Parameters Description
spaceId The ID or external label of the space the view belongs to.

Type: String
viewId The ID of the view to be updated.

Type: String
shareMode The desired sharing mode for the view. This can be SharedGlobally (shared with all spaces), SharedSelectively (shared with specific spaces) or NotShared (shared with no spaces).

Type: String
spaces (Optional) A list of space IDs (as integers) that the view can be shared with.

Include/uninclude a view

Include or remove a view from a space it has already been shared with.

Parameters Description
spaceId The ID of the space the view should be included into or removed from.

Type: String
id The ID of the view to be included/unincluded.

Type: String
include If True, the view will be included into the space. If False, the view will be removed from the space.

Type: Boolean
Default value: True
Valid options: True, False

The REST API can be used to modify the sharing options of charts, as well as include charts into other spaces.

Retrieve sharing details for a chart

Return sharing details for a chart, including the sharing mode (global/specific spaces/none) and the spaces it is shared with.

Parameters Description
spaceId The ID or external label of the space the chart belongs to.

Type: String
chartId The ID of the chart to be returned.

Type: String

Update chart sharing settings

Update the sharing settings of a chart, including changing the sharing mode or adding/removing spaces that the chart can be shared with.

Parameters Description
spaceId The ID or external label of the space the chart belongs to.

Type: String
chartId The ID of the chart to be updated.

Type: String
shareMode The desired sharing mode for the chart. This can be SharedGlobally (shared with all spaces), SharedSelectively (shared with specific spaces) or NotShared (shared with no spaces).

Type: String
spaces (Optional) A list of space IDs (as integers) that the chart can be shared with.

Include/uninclude a chart

Include or remove a chart from a space it has already been shared with.

Parameters Description
spaceId The ID of the space the chart should be included into or removed from.

Type: String
id The ID of the chart to be included/unincluded.

Type: String
include If True, the chart will be included into the space. If False, the chart will be removed from the space.

Type: Boolean
Default value: True
Valid options: True, False

Authentication

Requests to the API are authenticated using an API key which is passed in the Authorization header of each request. To get an API key, you have to log into Data Studio with your username and password first.

API keys

To generate an API key:

  1. Click the user icon in the top right corner and select Manage API keys.
  2. Click Create new API Key.
  3. Enter a name for the key and specify the number of days until it expires.
  4. Select the API permission(s) you want to associate with the key.
  5. Click Generate.
  6. Click Copy to take a copy of the generated key. You will have to paste it in the authorization header of your request.

There are multiple operations available through the Aperture Data Studio API. To add an additional layer of security, selected operations are allowed based on the user capabilities of the user creating the API key and API permissions associated with the API key.

Here are the user capabilities and API permissions required for each operation:

Request method & endpoint Required user capabilities Required API permissions
GET /{tenancyId}/sessions Installation Manager Audit operations (Read)
GET /{tenancyId}/events Installation Manager Audit operations (Read)
Request method & endpoint Required user capabilities Required API permissions
GET /{tenancyId}/datasets View Datasets Dataset operations (Read Dataset metadata)
GET /{tenancyId}/datasets/{spaceId} View Datasets Dataset operations (Read Dataset metadata)
GET /{tenancyId}/datasets/{spaceId}/{datasetId} View Datasets Dataset operations (Read Dataset metadata)
DELETE /{tenancyId}/datasets/{spaceId}/{datasetId} Create and Edit Datasets Dataset operations (Delete)
POST /{tenancyId}/datasets/load Create and Edit Datasets Dataset operations (Create)
GET {tenancyId}/datasets/load/{statusId} Create and Edit Datasets Dataset operations (Read Dataset upload status)
Request method & endpoint Required user capabilities Required API permissions
GET /{tenancyId}/views/{spaceId}/{viewId}/sharing Create and Edit Views View operations (Share Views)
PUT /{tenancyId}/views/{spaceId}/{viewId}/sharing Create and Edit Views View operations (Share Views)
PUT /{tenancyId}/views/{spaceId}/include Create and Edit Views View operations (Share Views)
Request method & endpoint Required user capabilities Required API permission
GET /{tenancyId}/charts/{spaceId}/{chartId}/sharing Create and Edit Charts Chart operations (Share Charts)
PUT /{tenancyId}/charts/{spaceId}/{chartId}/sharing Create and Edit Charts Chart operations (Share Charts)
PUT /{tenancyId}/charts/{spaceId}/include Create and Edit Charts Chart operations (Share Charts)
Request method & endpoint Required user capabilities Required API permissions
POST /{tenancyId}/jobs View Workflows & Execute Workflows Workflow operations (Submit Jobs)
GET /{tenancyId}/jobs Monitor Workflow Workflow operations (Read Jobs)
GET /{tenancyId}/jobs/{executionId} Monitor Workflow Workflow operations (Read Jobs)
Request method & endpoint Required user capabilities Required API permissions
GET /{tenancyId}/apiKey API access Rest API key operations (Read keys)
Request method & endpoint Required user capabilities Required API permissions
GET /metrics View System Information Metrics operations (Read)
GET /metrics/list View System Information Metrics operations (Read)
GET /metrics/{name} View System Information Metrics operations (Read)

Your authorization header should look like this:

{
    "Authorization": "<Environment external label> <Your API Key>"
}

The Environment's external label is used to identify the Environment in which the API key was generated. For users who have been assigned roles in multiple Environments, this information can be found in Data Studio's Manage Environments or Switch Environment pages. The default Environment's external label will be Default but the super admin can change this.

The authorization value is the external label followed by the API key, separated by a space.

In the event of an HTTP response with a 401 error status code, the possible causes are:

Possible cause Error message in HTTP response body
Missing user capabilities The API key must have the following capabilities: {required capabilities}
User (creator of API key) is disabled Unauthorized
Invalid API key Unauthorized
Expired API key Unauthorized
Missing API key Unauthorized
Missing API key permissions Unauthorized
Incorrect environment label Unauthorized
Missing environment label Unauthorized