9. Management API

MGRID Aperture has backend APIs that facilitate application integration. These APIs are focussed around usage statistics of Aperture itself, and providing a machine entrance for provisioning new users and projects. There is no access to data from datasources, user project definitions or project exports.

9.1. Json Web Tokens and root URL

The Backend API authentication is separate from the frontend authentication. Backend credentials cannot be used to obtain frontend access and vice versa. Backend credentials are set in the JWT Section of the configuration documentation.

9.2. Methods

9.2.1. /management/provision/project

9.2.1.1. GET

List summaries of all known provisioned projects.

Response:

A JSON array that contains for all known provisioned projects an object with id, name and description.

Example:

[{"id": 1, "name": "Test project A", "description": "Provisioned project A"},
 {"id": 2, "name": "Test project B", "description": "Provisioned project B"}]

Status Code:

  • 200 - Project summaries listed ok

  • 500 - Listing project summaries failed

Depending on the context the response body may contain more details about errors.

9.2.1.2. POST

Values in the body:
  • name (String)
  • description (String)
  • authgroup (String)
  • sftpexporttarget (Mapping)
    • host (String)
    • port (Integer)
    • user (String)
    • password (String) - (optional)
    • key (String) - (optional)
    • path (String)
  • deid_project_id (Integer) - (optional)
  • owner (String)
Accepted content types:
  • application/json

Define a new Aperture project.

Note that name must be unique among all projects, authgroup requires an inbound user to have LDAP group membership with a particular group, and either sftpexporttarget.password or sftpexporttarget.key must be provided.

Response:

A JSON object that contains a status string and project identifier. The identifier can be used as a key for successive calls to this interface.

Status Code:

  • 200 - New project provisioned ok

  • 409 - Project name already in use

  • 500 - Project provisioning failed

  • 502 - Upstream provisioning failed

Depending on the context the response body may contain more details about errors.

9.2.2. /management/provision/project/{id}

9.2.2.1. GET

List the summary for a provisioned project with given id.

Response:

A JSON object that contains an id, name and description.

Example:

{"id": 1, "name": "Test project A", "description": "Provisioned project A"}

Status Code:

  • 200 - Project summary listed ok

  • 404 - Project with id does not exist

  • 500 - Listing project summary failed

Depending on the context the response body may contain more details about errors.

9.2.2.2. PUT

Values in the body:
  • name (String)
  • description (String)
  • authgroup (String)
  • sftpexporttarget (Mapping)
    • host (String)
    • port (Integer)
    • user (String)
    • password (String) - (optional)
    • key (String) - (optional)
    • path (String)
  • deid_project_id (Integer) - (optional)
  • owner (String)
Accepted content types:
  • application/json

Update existing Aperture project with given id.

The project with the given identifier will be updated with the attributes set in this call.

This call is idempotent and can be used to retry an action that failed in a previous call. Note that the owner attribute cannot be changed after the first call. This is intentional.

Response:

A JSON object that contains a status string.

Status Code:

  • 200 - Existing project provisioned ok

  • 404 - Project with id does not exist

  • 409 - Project name already in use

  • 500 - Project provisioning failed

  • 502 - Upstream provisioning failed

Depending on the context the response body may contain more details about errors.

9.2.2.3. DELETE

Delete existing Aperture project with given id.

Response:

A JSON object that contains a status string.

Status Code:

  • 200 - Project deprovisioned ok

  • 404 - Project with id does not exist

  • 500 - Project deprovisioning failed

Depending on the context the response body may contain more details about errors.

9.2.3. /management/measurement/project

9.2.3.1. GET

List measurement summary for all known projects.

Response:

A JSON array that contains for all known projects the project id, name and size. The size corresponds with the database size in bytes for a particular project.

Status Code:

  • 200 - Project measurement listed ok

  • 500 - Listing measurement failed

Depending on the context the response body may contain more details about errors.

9.2.4. /management/dataset_import

9.2.4.1. POST

Values in the body:
  • project_name (String)
  • comments (str) - (optional)
  • filename_csv (str)
  • filename_def (str)
Accepted content types:
  • text/json

Define a new Aperture dataset.

Define a new dataset. project_name must point to an existing Aperture project. filename_csv and filename_def must be a path reachable and readable by the Aperture server. filename_def must contain a XML Schema Definition. filename_csv will be read with the filename_def definition in hand.

Response:

A JSON object that contains the status of the import.

Status Code:

  • 200 - Dataset import succeeded

  • 500 - Any server failure

Depending on the context the response body may contain more details about errors.

9.2.5. /management/ephemeral_dataset_import

9.2.5.1. POST

Values in the body:
  • project_name (String)
  • comments (str) - (optional)
  • filename_csv (str)
  • filename_def (str)
Accepted content types:
  • text/json

Define a new ephemeral Aperture dataset.

Define a new dataset. project_name must point to an existing Aperture project. filename_csv and filename_def must be a path reachable and readable by the Aperture server. filename_def must contain a XML Schema Definition. filename_csv will be read with the filename_def definition in hand.

Datasets processed using this entrypoint are ephemeral. After processing all knowledge about this dataset is dropped from Aperture. This is useful in situations where an enterprise wants to apply a preset policy on a dataset without that dataset becoming available for further use inside Aperture.

Response:

A JSON object that contains the status of the import.

Status Code:

  • 200 - Dataset import succeeded

  • 500 - Any server failure

Depending on the context the response body may contain more details about errors.

9.2.6. /management/external_dataset_import

9.2.6.1. POST

Values in the body:
  • project_name (String)
  • comments (str) - (optional)
  • filename_csv (str)
  • filename_def (str)
Accepted content types:
  • text/json

Define a new Aperture dataset to be reachable via an external uuid.

Datasets processed using this entrypoint will be available for reuse via a url by authorized users.

Note that the dataset will be subjected to the proscribed deidentification before storage in Aperture.

Values in the body:

Define a new dataset. project_name must point to an existing Aperture project. filename_csv and filename_def must be a path reachable and readable by the Aperture server. filename_def must contain a XML Schema Definition. filename_csv will be read with the filename_def definition in hand.

Response:

A JSON object that contains the status of the import.

Status Code:

  • 200 - Dataset import succeeded

  • 500 - Any server failure

Depending on the context the response body may contain more details about errors.

9.2.7. /management/provision/uploadtoken

9.2.7.1. POST

Values in the body:
  • user (String)
  • project (String)
Accepted content types:
  • application/json

Request a new upload token.

Given a user and a project name, request a timed upload token that the user can use to upload a new dataset into the project. The project to be used must be pre-provisioned.

Response:

A JSON object that contains a status and a token string.

Status Code:

  • 200 - Token returned

  • 404 - Project not found

    • User not authorized for project

  • 500 - Finding or creating user failed