API v1 - Notice

Overview

This is a guide to providing details on the Notice API services offered by Matillion ETL. These services provide the information associated with the "notices" available within the Matillion ETL instance. The Notice API is built on the Matillion ETL instance, which allows users to easily discover, integrate, analyse, enrich and consume the content through a single, consistent interface.

The API endpoints retrieve the data associated with the notices available in the instance. The Notice API family consists of Two PATHs that include the number of endpoint resources, using HTTP methods GET, POST, and DELETE.

Notices are stored in the tabs at the bottom-right of your Matillion ETL window. The 'Notices' tab will display any important messages regarding the instance, and can be automatically populated by Matillion ETL where problems are found.

Important Information

• This document is part of a series on Notices and the Matillion ETL API - v1.
• 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.
• 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.

---

Notice API Endpoints

API Base URL

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

API Endpoints and Function

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

Method	Path	URI	Function
PATH/notice
GET	/notice/	http://<InstanceAddress>/rest/v1/notice/	Get the list of notices.
POST	/notice/create	http://<InstanceAddress>/rest/v1/notice/create	To create a notice in the instance.
PATH/notice/id/{id}
GET	/notice/id/{id}/get	http://<InstanceAddress>/rest/v1/notice/id/{id}/get	Get a notice for the selected id.
POST	/notice/id/{id}/delete	http://<InstanceAddress>/rest/v1/notice/id/{id}/delete	To delete a notice via POST HTTP method.
DELETE	/notice/id/{id}	http://<InstanceAddress>/rest/v1/notice/id/{id}	To delete a notice with DELETE API request.

---

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.
<notice>	The list of notice available within the Matillion ETL instance.
<id>	Provides the id associated with the selected resource.
<create>	To create a notice within the instance.
<delete>	This property will delete the selected resource.
<get>	This property will get the resources from within Matillion ETL instance.

---

Endpoints and Server Response

This chapter describes the Notice API endpoints along with some examples from the server response. The Notice API endpoints offer REST-based web service, offering ease of use and a flexible choice of programming language. The Notice API endpoints can be used to access and analyze the notice and its id associated with the Matillion ETL instance.

Before we start working with any Notice endpoint call. It is recommended that you understand the concept of PATH used in the Notice API family.

A PATH is a unit of a REST API that you can call. A PATH includes an HTTP Method (GET/POST/DELETE) and a URL PATH that, when exposed, is combined with the base PATH URL (<server address>/rest/v1) of the API.

The Notice API family comprises of two PATHs:

• PATH/notice
• PATH/notice/id/{id}

PATH are relative to the API base URL. The full requested URL is constructed as : <Server address>/rest/v1/notice. API base URL (<Server address>/rest/v1/) is the prefix for all API paths, relative to the host root(i.e Server address or InstanceAddress). PATH and a HTTP method combined defines a unique operation for the resources.

To illustrate the Notice API, endpoints and methods to the further, below is a diagram of the /notice endpoint showing possible PATH, GET and POST and DELETE options.

Once, you have basic understanding of PATH and associated HTTP methods, you can start making API requests.
All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the data used to get, add or delete the notice. The detailed description of each endpoint and associated methods is discussed in the next section of this guide.

---

PATH/notice

List of endpoints for the PATH/notice:

• GET/notice
• POST/notice/create
• PATH/notice/id/{id}

Below is the detailed description of these endpoints with the server response examples.

GET/notice

This example is a GET method REST API request that will provide the list of available notices within the Matillion ETL instance.

• Base URL

  http://<InstanceAddress>/rest/v1/notice/

• Server Response

  [
      "mtln-cdc-queue-error",
      "123453",
      "mtln-sqs-error",
      "12345",
      "12343",
      "12346"
  ]

POST/notice/create

This endpoint allows to post a new server-side notice to the instance. This will be a POST method API call as we will have to attach the information, in the body as a JSON format to import into the Matillion ETL instance.

• Base URL

  http://<InstanceAddress>/rest/v1/notice/create

• POST Body(JSON)

  {
     "title":"MyNoticeTitle",
     "details": "YourNoticeMessage",
     "id": "12345",
     "level":"INFO",
     "dismissable":true
  }
  

Below is the description of the fields included in the POST body:

Field name	Data type	Description
title	String	The title for the notice to create.
details	String	The message for the notice.
id	String	The unique numeric id associated for the notice.
level	String	The level of information through the notice. It can be "INFO" or "WARNING".
dismissable	Boolean	This can be true or false

• Server Response

  {
    "success": true,
    "msg": "Successfully created a new Notice with the ID [12345].",
    "id": 0
  }

---

PATH/notice/id/{id}

PATH/notice/id/{id} is a part of the PATH/notice family, which is further combined with three separate HTTP methods GET, POST, and DELETE.

List of endpoints associated with the PATH/notice/id/{id}

• GET/notice/id/{id}/get
• POST/notice/id/{id}/delete
• DELETE/notice/id/{id}

Below is the detailed description of these endpoints with the server response examples.

GET/notice/id/{id}/get

This is a GET request API call to retrieve the information of the selected notice using the id (unique identification number) associated with it.

• Base URL

  http://<InstanceAddress>/rest/v1/notice/id/<id>/get

• Server Response

  {
    "noticeID": "12345",
    "origin": "SERVER",
    "level": "INFO",
    "title": "MyNoticeTitle",
    "issuedTime": 1592561202824,
    "details": "YourNoticeMessage",
    "dismissable": true
  }

POST/notice/id/{id}/delete

This is a POST request API call to delete the information of the selected notice using the id.

• Base URL

  http://<InstanceAddress>/rest/v1/notice/id/<id>/delete

• Server Response

  {
    "success": true,
    "msg": "Successfully deleted the Notice with the ID [12345].",
    "id": 0
  }

DELETE/notice/id/{id}

This is a DELETE request API call to delete the information of the selected notice.

• Base URL

  http://<InstanceAddress>/rest/v1/notice/id/<id>

• Server Response

  {
    "success": true,
    "msg": "Successfully deleted the Notice with the ID [12345].",
    "id": 0
  }

---