Skip to content

Getting started with Postman

Overview

This guide details the Matillion ETL API, and describes the general usage of APIs using a particular graphical user interface (GUI) client, Postman, along with some examples.

When you are testing or experimenting with endpoints using different parameters, you will likely use one of the many GUI REST clients available to create the API requests. GUI clients are advantageous because they streamline the testing of REST APIs.

There are various GUI clients available, but for this guide, we will cover Postman.

Important Information and Links

  • Users responsible for experimenting with Matillion ETL API services require access to the Matillion ETL instance.
  • If you haven't already done so, please download and install the Postman app.
  • For more information on Matillion ETL API v1, please refer to our support documentation on Matillion ETL API - v1.
  • For more information on making REST API requests using the command line interface cURL, please refer to our support documentation on Getting Started with cURL.

How to use Postman and its Features

Pictured below is the Postman "Workspace".

Postman Startup Screen

Postman Startup Screen

Numbers Feature Name Description
New This is where users can create a new request, collection, or environment.
Import Typically used to import a collection or environment. There are options such as folder, link, import from file, or paste raw text to import. More...
Runner This is a Collection Runners, Automation tests can be executed through this. More...
Open New This is a clickable button to open a new tab, Postman Window, or Runner.
My Workspace Users can create a new workspace individually or as a team. More...
Invite Users can invite new team members to collaborate on a workspace.
History This tab will display the past requests that a user has sent. The History tab makes it easy to track actions.
Collections Users can organize test suites by creating collections. Each collection may have many subfolders and multiple requests. A request or folder can also be duplicated as well.
Request tab The Request tab displays the title of the URL request the user is working on. By default, "Untitled Request" is displayed for requests that lack a title.More...
HTTP Request This is a dropdown button that will display the list of different request options available. This list is extensive, but includes very common requests, such as GET, POST, COPY, and DELETE. Normally in testing an API, the most commonly used requests are GET and POST.
Request URL The Request URL is also known as an endpoint. This is where users can identify the link to where the API will be directing, and the expected result of the API call.
Save Use this button to save requests. More...
Params Short for "parameters", this tab is where users can write parameters needed for a request, such as key values.
Authorization To make any REST API call, authorization is required. It may be in the form of a username and password, API key, bearer token, etc.
Headers This tab allows users to set headers such as "content-type" as JSON/application, "content-Length", "connection", and many more, depending on the needs of the organization.
Body Here users can supply the body or can customize details commonly used in POST requests.
Pre-request Script These are scripts that will be executed some time before the request has been made. Ordinarily, pre-request scripts for the setting environment are used to guarantee that tests will be run within the rectify environment.
Tests These are scripts executed during the request. Tests benefit users by manifesting as checkpoints to verify whether or not a response status is "OK", retrieved data is as expected, and other tests.

Enable Authorization

The Matillion ETL API requires authentication to make any REST API call. The Matillion API uses HTTP Basic Authentication. The details of the HTTP basic authentication are beyond the scope of this document, but it essentially requires a username and password—specifically, of the corresponding Matillion ETL instance.

In Postman, navigate to the Authorization header. Select Basic Auth from the dropdown and enter the Username and Password of the Matillion ETL instance.

Postman Authorization

Postman Authorization

Please Note

Postman supports different methods of authentication, including: No Authentication, Basic Authentication (provide username and password only), Digest Authentication, OAuth 1.0, OAuth 2.0, Hawk Authentication, AWS Signature, and NTML Authentication [Beta].

For more information on authentication, we recommend the Postman documentation.

GET Requests in Postman

Summary

GET requests are used to retrieve information from the passed URL. No changes are performed on the endpoint. The GET request is the default method when making HTTP calls using Postman.

The example below retrieves a list of resources within a Matillion ETL group via a GET request for a resource endpoint.

Base URL

https://<instance address>/rest/v1/group/name/<groupName>/project

How to Make a GET Request in Postman

To make a GET request in Postman, follow these steps:

  1. Select the method (the action type) from the dropdown. The default method is GET.
  2. Input the API endpoint URL in the "Enter request URL" field.
  3. Click the Authorization tab and provide authorization credentials.
  4. Click the Send button to execute this API request. Users can save their API request to the library.
  5. Next, users will see a server response with the code status. Upon success, users will receive a "Status: 200 OK" message, which means that the API request was successful.
  6. In this example, there should be a list of "projects" available in the Body tab. The presence of this retrieved information indicates that the test has run successfully.

Server Response

Postman GET Request

Postman GET Request

How to Make a GET Export Request in Postman

Summary

In the example below, we will export a project named "Example-project" from a Matillion ETL project. To export the project, provide the project's name and use the /export endpoint.

This request is a GET API request to export the selected resource's details and all associated information such as variables, environments, schedules, versions, jobs, and more details alligned with the project.

Please Note

This is another example of a GET API request. For instructional guidance, follow the same steps as mentioned in the GET example above.

Base URL

https://<instance address>/rest/v1/group/name/<groupName>/project/name/Example-project/export

Server Response

Postman GET/export Request

Postman GET/export Request


How to Make a POST Import Request in Postman


Summary

In this example, we use the Matillion API v1 to import the above project into a Matillion ETL instance. When importing, there is no "merge" option. If a resource of the same name already exists, you must delete the existing resource before importing the new.

This API call will be a POST call. This task will require attaching the project (in JSON form, which is the format it was also exported), into the Body tab as a JSON file to import the project into the target Matillion ETL instance.

Guidance for making this POST request is below.

Base URL

https://<instance address>/rest/v1/group/name/<groupName>/project/import

How to make a POST request in the Postman Workspace

  1. Click to create a new request.
    2. Create New Request

    Create New Request

  2. Click the dropdown menu labelled "2" to select the API method (the action type). For this example we select POST.
  3. Input the API endpoint URL in the "Enter request URL" field.
  4. Click the Authorization tab, and enter relevant Matillion credentials.
    5. Enter details

    Enter details

  5. Click the Body tab, and perform the following tasks:
    • Click the raw button.
    • Select JSONfrom the dropdown.
    Body Postman

    Body Postman

  6. In this example, the imported body for the POST is a Matillion ETL project named "APIImported". 
       {
    "objects": [
        {
            "name": "APIImported",
            "variables": []
         "environmentExports": {
                "objects": []
              "version": "1.44.11",
                "environment": "redshift"
                },
         "scheduleExports": {
                "objects": [],
                "version": "1.44.11",
                "environment": "redshift"
            },
            "versionExports": {
                "objects": []
    }
    Body Postman

    Body Postman

    Please Note

    • The API request must have the correct format to ensure that requested data will be created. We recommend making a GET request first to check the JSON format of the request.
    • Ensure that the code has been copied correctly with paired curly braces and brackets.
    • Change the project name "APIImported" to any desired name to avoid any conflict with pre-existing projects. You can also change other details, such as the the id, variables, and more.
  7. Click the Send button, which is located to the right of the API request field. Users can save their API request to the library.
  8. Next, users will see a server response with the code status. Upon success, users will receive a "Status: 200 OK" message, which means that the API request was successful.
  9. Existence of a new Matillion ETL project named "APIImported" in the JSON body indicates that the POST has run successfully.
Server Response POST Request

Server Response POST Request


How to Make a DELETE Request in Postman


Summary

In the example below, we will delete an existing project in the group, named "Example-project". We will be using the DELETE method to remove the project within the list.

Base URL

http://<instance address>/rest/v1/group/name/<groupName>/project/name/<projectName>

How to make a DELTE requqest in the Postman Workspace

  1. Click to create a new request.
  2. Click the dropdown menu labelled "2" to select the API method (the action type). For this example we select DELETE.
  3. Input the API endpoint URL in the "Enter request URL" field.
  4. Click the Authorization tab and provide authorization credentials.
  5. Click the Send button to execute this API request. Users can save their API request to the library.
  6. Next, users will see a server response with the code status. Upon success, users will receive a "Status: 200 OK" message, which means that the API request was successful.
  7. A successful DELETE will return the following message "Success deleted Project: project-name".

Server Response

Server Response DELETE Project

Server Response DELETE project

Please Note

There are often multiple ways of achieving the same task within the API as resources and methods branch out and overlap.


Additional Postman Examples


PATH/Job Endpoint - jobName/export


Summary

The below example exports a Matillion ETL project's job. This is a GETrequest. Below is outlined the export URL for a single Matillion ETL job.

Base URI

http://<instance address>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/job/name/<jobName>/export

Postman Server Response

Server Response Job Export

Server Response Job Export


PATH/job Endpoint - job/import


Summary

To import a Job into a Matillion ETL project, use the URL below. This API request is a POST, and therefore the Matillion job must be added as a JSON file after clicking the Body tab.

Retrieve the job's details using jobname/export endpoint (as mentioned in the previous example) and then copy and paste the content into the Body tab that sits within the upper level Body tab. Please ensure you change the name of the job to avoid any conflict with any job of the same name.

Base URL

http://<instance address>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/job/import

Server Response

Postman Response-Import Job

Postman Response-Import Job


PATH /version Endpoint - Get/id


Summary

The Get/id endpoint is from the family of PATH/version. This endpoint will provide the id of the selected version name. To get the id, use the URL below.

Base URL

http://<instance address>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/id

Server Response


Server Response - Version id

Server Response - Version id


OAuth Endpoint - Get/properties


Summary

This endpoint permits the API to recover the properties of the chosen OAuth. This endpoint is from the familiy of OAuth. The properties of the OAuth includes: "CallbackURL", "AccountId", "AccessToken", "Clientsecret", "ClientId", "DeveloperToken", "CustomerId", "Verifier", "settings", and other data. For more information about creating and authenticating OAuth entries in Matillion ETL, read our Manage OAuth guide.

Base URL

http://<instance address>/rest/v1/oauth/name/<oauth Name>/properties

Server Response

Server Response - OAuth properties

Server Response - OAuth properties


URL Parameters and Description

Below is the list of endpoint parameters (used in the guide) and a brief description of each:

Parameter Name Description
<instance address> This is the server IP address or domain name.
<version> This is the API version. This does not relate to Matillion ETL versions.
<endpoint> An endpoint is the part of the API used to make an API call.
<groupName> The name of the group created in the Maillion ETL instance.
<projectName> The name of a Matillion ETL project.
<scheduleName> The name of a Matillion ETL schedule.
<versionname> The name of a Matillion ETL version.
<jobName> The name of a Matillion ETL Orchestration Job or Transformation Job.
<delete> Used to delete a resource.
<oauthProperties> Used to acquire properties associated with a select OAuth in a corresponding Matillion ETL instance.
<oauthName> Provide the OAuth name from the Matillion ETL instance, accessed through Project → Manage OAuth.
<id> The id associated with the chosen version of the API.

Video Guide