API v1 - Audit

API v1 - Audit


Overview

This is a guide to providing details on the Audit API services offered by Matillion ETL. These services provides the Audit log data using the API call request. The Audit API endpoint is of singular function usable only by users running an Enterprise Edition Matillion ETL instance.

Audit API provides the "resource" data (“Resources” refers to the information returned by an API). These resources usually have various endpoints which are combined with multiple HTTP methods for each endpoint. Audit API endpoint uses only GET method to retrive the data and export the log data within the Matillion ETL instance.

Important Information

  • Users responsible for experimenting with Matillion ETL API services require access to the Matillion ETL instance and ought to know how to make REST API calls either employing a REST API GUI client such as Postman or employing a command-line interface like cURL.
  • For more information about accessing the Matillion API, and general information on the Matillion API platform before using the API, please refer to Matillion ETL API - v1.
  • Matillion ETL API endpoints require authorisation to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Audit API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/<audit>

API Endpoints and Function

Audit API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET and POST data. The Audit API service is accessed through the Uniform Resource Identifier (URI). All following references in this document will assume the API Base URL has been specified. The available API endpoints are listed below:

Method Path URI Function
GET /audit http://<InstanceAddress>/rest/v1/audit Retrieve the audit log available in the instance.
GET /audit/export http://<InstanceAddress>/rest/v1/audit/export?offset=0&limit=25 To export the audit log.



URL Parameters and Description

Below is the list of endpoint parameters and their brief description:

Parameters Name Description
<InstanceAddress> This is the server IP address or domain name.
<audit> The audit log witin the instance.
<export> This property export the data in the instance.

Endpoints and Server Response

This chapter describes the Audit API endpoints and examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language. These APIs can be used to access and analyse the users data, export and import within the Matillion ETL instance.

All the APIs listed in this chapter are available to use with GET method to retrieve or export the audit data within the Matillion ETL instance. The detailed description of each endpoint and associated methods is discussed below.

GET/audit

In the example below, we will be retrieving a single resource information, perform a GET request for that named resource endpoint. The endpoint will retrieve the audit log within the instance.

Whenever you reach a named resource endpoint, the API will expose API metadata for that resource, including PATH, GET and POST and DELETE method options available. In the example below, the metadata would show PATH options for the /audit.

  • Base URL
    http://<InstanceAddress>/rest/v1/audit
  • Server Response
    {
      "endpoints": [
        {
          "httpMethod": "PATH",
          "name": "AuditService",
          "children": [],
          "type": "AuditService"
        }....
      ],
      "dataTypes": []
        {},
        {
          "type": "EndpointArgumentStyle",
          "possibleValues": [
            "QUERY",
            "PATH",
            "DATA"
          ]
        },....
        {
          "type": "HttpMethod",
          "possibleValues": [
            "GET",
            "PUT",
            "POST",
            "DELETE",
            "PATH"
          ]
        },....
    }

GET/export

This is a Get request API call, which will export the audit log JSON file available within the Matillion ETL instance by adding /export endpoint in the base URI.

  • Base URL
    http://<InstanceAddress>/rest/v1/audit/export
  • Server Response
    {
      "list": [
        {
          "id": 2135092,
          "specifier": "Project Group (Demonstration Projects) [2] - Project (Ian Funnell) [44359] - Version (default) [44360] - Job (Salesforce Viewer) [1362467] - Components [2134634 (tmp_sf_demo), 2134653 (SQL 3), 2134662 (Aggregate 3)]",
          "commandType": "DeleteTransformationItems",
          "user": "ec2-user",
          "timestamp": 1592932292974
        },
        {
          "id": 2135065,
          "specifier": "Project Group (Demonstration Projects) [2] - Project (Kevin Healey) [1734452] - Version (default) [1734453] - Job (API ip-ranges) [2053039] - Component (API Query 0) [API Query] [2053043] - Parameter (Data Selection) [7]",
          "commandType": "SetParameterElements",
          "user": "ec2-user",
          "timestamp": 1592926214834
        },
      ],
      "offset": 0,
      "totalLength": 1344
    }
  • Please Note

    The Audit log will be downloaded as JSON where each entry shows a significant action within a Matillion Instance. Most actions by users are logged here in detail such that they are accountable for any changes made.

    Below is the description of the fields included in the Server Response of Audit log JSON body:

    Field Name Description
    <id> The ID of the audited action.
    <specifier> A hierarchical path to the point of action. For example: If a user changes a component parameter, the specifier will give the parameter change, the component, the job, the version and the project that it belongs to. Thus, the specifier can give a direct path to recreate the change the user enacted.
    <commandType> A quick reference for the type of action performed. Command Types are named in a self-explanatory matter. For example, deleting a job yields the Command Type 'DeleteJobs' and creating an orchestration component yields CreateOrchestrationComponent.
    <user> The name of the user than enacted this change.
    <timestamp> The time (based on the server's timezone) that the change occurred.