Use the REST API

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

Create a Dataset

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

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

Retrieve a Dataset

There are three ways to retrieve a Dataset:

1. Retrieve a list of Datasets based on the tenancyId or tenancy external label only.
2. Retrieve a specific Dataset based on the combination of: tenancyId or tenancy external label, spaceId or space external label and datasetId or dataset external label.
3. Retrieve a list of Datasets in a Space based on the combination of: tenancyId or tenancy external label and spaceId or space external label.

The returned information is:

• Dataset ID
• Dataset UUID
• Dataset type
• Dataset name
• Dataset summary
• Dataset description
• Dataset external label
• Dataset enableDropZone settings
• Dataset publish OData settings
• Dataset batch settings
• Dataset batch limit
• Dataset allow batch deletion settings
• Dataset allow auto refresh settings
• Space where Dataset is uploaded
• Space ID where Dataset is uploaded
• Source Type which using to upload the Dataset:
  • External system (This is only applicable for source type external system.)
  • Credentials (This is only applicable for source type external system.)
• Dataset tables:
  • Table UUID
  • Table name
  • Table summary
  • Table description
  • Table Columns
    • Column UUID
    • Column data type
    • Column name
    • Column description
    • Column tags

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.

You can use the REST API to create and manage Spaces.

Create a Space

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

Retrieve a Space

There are two ways to retrieve a Space:

1. Retrieve a list of Spaces based on the tenancyId or tenancy external label only.
2. Retrieve a specific Space based on the combination of: tenancyId or tenancy external label and spaceId.

The returned information is:

• Space name
• Space description
• Space external label
• Space allow data exposure status
• Space permissions details:
  • Space permission type
  • Space assigned user/user group type
  • Space assigned user/user group ID
  • Space assigned user/user group UUID
  • Space assigned user/user group name
  • Space assigned username
• Space schema
• Space ID
• Space UUID

Update/Patch a Space

To update/patch a Space, you have to use the combination of tenancyId or tenancy external label and spaceId parameter which is defined in the Space properties. The following parameters have to also be supplied:

Once updated/patched, the Space information will be changed accordingly.

Delete a Space

To delete a Space you have to use the combination of tenancyId or tenancy external label and spaceId. Once deleted, a successful operation with no content will be returned.

You can use the REST API to create and manage users.

Create a user

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

Retrieve a user

There are two ways to retrieve a user:

1. Retrieve a list of users based on the tenancyId or tenancy external label only.
2. Retrieve a specific user based on the combination of: tenancyId or tenancy external label and userId.

The returned information is:

• User name
• Username for login
• User email
• Role details:
  • Role ID
  • Role UUID
  • Role name
• User status
• User installation manager status
• User authentication type
• User ID
• User UUID
• User password expired status
• User last login date
• User locked until date
• User super admin status

Update/Patch a user

To update/patch a user, you have to use the combination of tenancyId or tenancy external label and userId parameter which is defined in the User properties. The following parameters have to also be supplied:

Once updated/patched, the user information will be changed accordingly.

Delete a user

To delete a user, you have to use the combination of tenancyId or tenancy external label and userId. Once deleted, a successful operation with no content will be returned.

You can use the REST API to create and manage user groups.

Create a user group

When creating a user group, the following parameters can be supplied:

Retrieve a user group

There are two ways to retrieve a user group:

1. Retrieve a list of user groups based on the tenancyId or tenancy external label only.
2. Retrieve a specific user group based on the combination of: tenancyId or tenancy external label and userGroupId.

The returned information is:

• User group name
• User group summary
• User group description
• The user group member details:
  • User member type
  • User ID
  • User UUID
  • Username
• User group ID
• User group UUID

Update/Patch a user group

To update/patch a user group, you have to use the combination of tenancyId or tenancy external label and userGroupId parameter which is defined in the User Group properties. The following parameters have to also be supplied:

Once updated/patched, the user group information will be changed accordingly.

Delete a User Group

To delete a user group, you have to use the combination of tenancyId or tenancy external label and userGroupId. Once deleted, a successful operation with no content will be returned.

You can use the REST API to create and manage user roles.

Create a role

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

Retrieve a role

There are two ways to retrieve a role:

1. Retrieve a list of roles based on the tenancyId or tenancy external label only.
2. Retrieve a specific role based on the combination of: tenancyId or tenancy external label and roleId.

The returned information is:

• Role name
• Role summary
• Role description
• Role locked down settings
• Role manager details:
  • Role manager ID
  • Role manager UUID
  • Role manager user ID
  • Role manager name
• Role capabilities
• Role ID
• Role UUID

Update/Patch a role

To update/patch a role, you have to use the combination of tenancyId or tenancy external label and roleId parameter which is defined in the Role properties. The following parameters have to also be supplied:

Once updated/patched, the role information will be changed accordingly.

Delete a role

To delete a role, you have to use the combination of tenancyId or tenancy external label and roleId. Once deleted, a successful operation with no content will be returned.

You can use our API to execute a specific Workflow or to get 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:

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

Retrieve a Job

To retrieve a list of Jobs from Data Studio, you need to specify the tenancyId or tenancy external label.

The return information is:

• Job execution ID
• Space where job is executed
• Job name
• Job start time
• Job end time
• Job execution duration
• Job error message
• Job latest message
• Job status
• Job step details
  • Job step ID
  • Job step name
  • Job step start time
  • Job step end time
  • Job step duration
  • Job step status
  • Job step progress

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
• Details for each step completed within that Workflow

The current state can be any of the following:

Retrieve Workflow settings

You can use the API to retrieve the settings of a selected Workflow.

To do that, you have to specify the following fields in your path parameter:

Information returned is:

• The external label of the Workflow
• Details of each Source step within the Workflow
• Details of each Workflow parameter
• Workflow version (draft or published)

You can use the API to retrieve a list of exportable objects and export related metadata.

Retrieve an exportable object

To retrieve a list of exportable objects (draft/published version) in a Space, you need to specify the combination of tenancyId or tenancy external label and spaceId or space external label.

The returned information is:

• Exportable object type
• Object details:
  • Object ID
  • Object name
  • Object summary
  • Object status version
  • Object dependencies:
    • Object type
    • Object ID
    • Object name
  • Object force dependencies

Export metadata

To export metadata, you have to use the combination of tenancyId or tenancy external label, spaceId or space external label and object version allowDraftVersions parameter which is defined in the Export properties. The following parameters have to also be supplied.

Export a metadata will return a Download file link which you can use to download the .dmx/.dmxd file.

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 API Upload operation to upload a Data Studio metadata file (.dmx or .dmxd) and then import or synchronize the metadata into a Space.

Import metadata

To import metadata, you have to use the combination of tenancyId or tenancy external label and spaceId or space external label parameter which is defined in the Import properties. The following parameters have to also be supplied.

The returned information is:

• Import test mode
• Number of objects imported
• Number of errors during import
• Number of warnings during import
• General error during import
• Import object with errors
• Import object with warning
• Import object responses:
  • Object type
  • Name
  • Source UUID
  • Target UUID
  • Import action
  • Import action info
  • Errors
  • Object warnings
  • Data warnings
  • Target has draft
  • Target external label
  • Has data

Synchronize metadata

To Synchronize metadata, you have to use the combination of tenancyId or tenancy external label and spaceId or space external label parameter which is defined in the Synchronize properties. The following parameters have to also be supplied.

The returned information is:

• Import test mode
• Number of objects imported
• Number of errors during import
• Number of warnings during import
• General error during import
• Import object with errors
• Import object with warning
• Import object responses:
  • Object type
  • Name
  • Source UUID
  • Target UUID
  • Import action
  • Import action info
  • Errors
  • Object warnings
  • Data warnings
  • Target has draft
  • Target external label
  • Has data

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:

You can use the REST API to retrieve the list of API key access based on the tenancyid or tenancy external label.

The returned information is:

• API Key permission list
• API Key name
• API Key creation date
• API Key expiration data
• API Key status
• Environment name where API Key is created

You can execute a Schedule and monitor its status through our API. This is particularly useful if you plan to use Schedules to group Workflows together.

Execute a Schedule

To execute a Schedule, you have to specify its external label under the Schedule wizard.

Executing a Schedule through our API will return executionId which you can use to check the execution status of the Schedule.

Check the status of Schedule execution

The API allows you to query the status of all recently executed Schedules using the executionId.

The returned information is:

• Space where the Schedule is executed
• Schedule name.
• Who initiated the Schedule.
• Start time
• End time.
• Overall Schedule execution status.
• Status for each underlying Workflow:
  • Workflow name
  • Start time
  • End time
  • Execution duration
  • Workflow execution status

The REST API can be used to modify the sharing options of Functions.

Retrieve sharing details for a Function

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

Update Function sharing settings

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

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.

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.

Include/uninclude a chart

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

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.

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.

Include/uninclude a view

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

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

Retrieve sharing details for a Workflow

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

Update Workflow sharing settings

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

Include/Exclude a Workflow

Include or remove a Workflow from a Space it has already been shared with.

You can use the API to upload a Data Studio metadata files (.dmx or .dmxd) or any other supported formats:

• .csv
• .txt
• .xls
• .xlsx
• .sas7bdat
• .psv
• .json

To upload file metadata, you have to first choose the .dmx/.dmxd file then import/synchronize back the metadata.

Uploading a file will return a fileKey which you will need for the import/synchronize or create Dataset operations.