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.

How to use Postman and its Features

Pictured below is the Postman "Workspace".

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

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

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.

Base URL

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

Server Response

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.


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.


Enter details

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


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

   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

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

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

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

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

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

URL Parameters and Description

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

Video Guide