API v1 - Notice

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. Notice API family consist of Two PATHs that combined with number of endpoint resources using HTTP methods GET, POST, and DELETE.

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

Notices

Notices

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 . Notice API endpoints offers 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 analyse the notice and its id associated with the Matillion ETL instance.

Before we start working with any Notice endpoint call. It would be recommended to understand the concept of PATH used in Notice API family.

A PATH is a unit of a REST API that you can call. A PATH comprises 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 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.
 

Notice endpoint Flow

Notice endpoint Flow

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:

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 notice 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 Description
    <title> The title for the notice to create.
    <details> The message for the notice.
    <id> The unique numeric id associated for the notice.
    <level> The level of information through the notice. It can be Info or Warning.
    <dismissable> 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 seperate HTTP methods GET, POST, and DELETE.

List of endpoints associated with the PATH/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
    }