API v1 - Audit

Overview

This is a guide to providing details on the Audit API services offered by Matillion ETL. 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 ("resource" refers to the information returned by an API). These resources usually have various endpoints that are combined with multiple HTTP methods for each endpoint. The Audit API endpoint uses only the GET method to retrieve the data and export the log data within the Matillion ETL instance.

:::info{title='Note'}

• 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 by employing a REST API GUI client such as Postman, or employing a command line interface (CLI) 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 authorization to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.
• The Audit API endpoint is available for admin users of Matillion ETL. :::

---

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 use HTTP or HTTPS requests 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 base URI 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 within the instance.
<export>	Export the data in the instance.

---

Endpoints and server responses

All the APIs listed in this section are available to use with the GET method to retrieve or export the audit data within your 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's information by performing 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, POST, and DELETE. In the example below, the metadata shows 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 to the base URI.

• Base URL

http://<InstanceAddress>/rest/v1/audit/export

• Server Response

        {
          "list": [
            {
              "id": 2135092,
              "specifier": "Project Group (Demonstration Projects) [2] - Project (John Smith) [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 (Ewan Mack) [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
        }

:::info{title='Note'} The audit log will be downloaded as JSON where each entry shows a significant action within a Matillion ETL 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 the 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 who enacted this change.
<timestamp>	The time (based on the server's timezone) that the change occurred.