Articles in this section

See more

IO management API

  • Updated
Follow

Overview

These API endpoints are used to add, edit, or delete Connections/ Listeners/ Formats. 

Authentication

Before making a call to the built-in API, the user must receive a JWT token from the authentication API.

Step 1. Use any user with the Editor or Administrator role to call Etlworks authentication endpoint and receive an access token.

Step 2. Use the access token received in Step 1 to call Etlworks API endpoints. The access token must be submitted as a header parameter, as in: Authorization:Bearer access-token.

Note: Access tokens in Etlworks are short-lived and self-expiring. An access token gives you access to the APIs for approximately 10 minutes. It is recommended that you refresh the access token before each call to the API.

Connections API

Add new Connection

Important: The API endpoint parameters

  • PATH: /rest/v1/connections

EXAMPLE: https://app.etlworks.com/rest/v1/connections

  • METHOD: POST
  • HEADER: Authorization:Bearer access-token 
  • REQUEST BODY: JSON document in the following Format:
  • {
        "name": string, the name
        "description": string, the description
        "connectionType": string, the connection type
        "properties": object, the map of properties
        "tags": array, the list of tag strings
    }
  • REQUEST CONTENT TYPE: application/json.

Response

The response is a JSON document in the following Format:

{
    "id": number, the ID
    "name": string, the name
    "description": string, the description
    "connectionType": string, the connection type
    "properties": object, the map of properties
    "tags": array, the list of tag strings
}

Response Codes

  • 200 for success
  • 400 for the not valid request body
  • 401 for not authorized
  • 403 for forbidden,
  • 500 for an internal error

Edit Connection

Important: The API endpoint parameters

  • PATH: /rest/v1/connections/{connectionId}

EXAMPLE: https://app.etlworks.com/rest/v1/connections/1

  • METHOD: PUT
  • HEADER: Authorization:Bearer access-token 
  • REQUEST BODY: JSON document in the following Format:
  • {
        "id": number, the ID
        "name": string, the name
        "description": string, the description
        "properties": object, the map of properties
        "tags": array, the list of tag strings
    }
  • REQUEST CONTENT TYPE: application/json.

Response

The response is a JSON document in the following Format:

{
    "id": number, the ID
    "name": string, the name
    "description": string, the description
    "connectionType": string, the connection type
    "properties": object, the map of properties
    "tags": array, the list of tag strings
}

Response Codes

  • 200 for success
  • 400 for the not valid request body
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Delete Connection

Important: The API endpoint parameters

  • PATH: /rest/v1/connections/{connectionId}

EXAMPLE: https://app.etlworks.com/rest/v1/connections/1

  • METHOD: DELETE
  • HEADER: Authorization:Bearer access-token 
  • REQUEST BODY: none
  • REQUEST CONTENT TYPE: none
  • RESPONSE: none

Response Codes

  • 204 for success
  • 401 for not authorized
  • 403 for forbidden
  • 409 if a Connection cannot be deleted because it is referenced in some Flow
  • 500 for an internal error

Listeners API

Add new Listener

Important: The API endpoint parameters

  • PATH: /rest/v1/listeners

EXAMPLE: https://app.etlworks.com/rest/v1/listeners

  • METHOD: POST
  • HEADER: Authorization:Bearer access-token 
  • REQUEST BODY: JSON document in the following Format:
  • {
        "name": string, the name
        "description": string, the description
        "connectionType": string, the listener type
        "properties": object, the map of properties
        "tags": array, the list of tag strings
    }
  • REQUEST CONTENT TYPE: application/json.

Response

The response is a JSON document in the following Format:

{
    "id": number, the ID
    "name": string, the name
    "description": string, the description
    "connectionType": string, the listener type
    "properties": object, the map of properties
    "tags": array, the list of tag strings
}

Response Codes

  • 200 for success
  • 400 for the not valid request body
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Edit Listener

Important: The API endpoint parameters

  • PATH: /rest/v1/listeners/{listenerId}

EXAMPLE: https://app.etlworks.com/rest/v1/listeners/1

  • METHOD: PUT
  • HEADER: Authorization:Bearer access-token 
  • REQUEST BODY: JSON document in the following Format
  • {
        "id": number, the ID
        "name": string, the name
        "description": string, the description
        "properties": object, the map of properties
        "tags": array, the list of tag strings
    }
  • REQUEST CONTENT TYPE: application/json.

Response

The response is a JSON document in the following Format:

{
    "id": number, the ID
    "name": string, the name
    "description": string, the description
    "connectionType": string, the listener type
    "properties": object, the map of properties
    "tags": array, the list of tag strings
}

Response Codes

  • 200 for success
  • 400 for the not valid request body
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Delete Listener

Important: The API endpoint parameters

  • PATH: /rest/v1/listeners/{listenerId}

EXAMPLE: https://app.etlworks.com/rest/v1/listeners/1

  • METHOD: DELETE
  • HEADER: Authorization:Bearer access-token
  • REQUEST BODY: none
  • REQUEST CONTENT TYPE: none
  • RESPONSE: none

Response Codes

  • 204 for success
  • 401 for not authorized
  • 403 for forbidden
  • 409 if the Listener cannot be deleted because it is referenced in some Flow
  • 500 for an internal error

Formats API

Add new Format

Important: The API endpoint parameters

  • PATH: /rest/v1/formats

EXAMPLE: https://app.etlworks.com/rest/v1/formats

  • METHOD: POST
  • HEADER: Authorization:Bearer access-token
  • REQUEST BODY: JSON document in the following Format:
  • {
        "name": string, the name
        "description": string, the description
        "formatType": string, the format type
        "properties": object, the map of properties
        "tags": array, the list of tag strings
    }
  • REQUEST CONTENT TYPE: application/json.

Response

The response is a JSON document in the following Format:

{
    "id": number, the ID
    "name": string, the name
    "description": string, the description
    "formatType": string, the format type
    "properties": object, the map of properties
    "tags": array, the list of tag strings
}

Response Codes

  • 200 for success
  • 400 for the not valid request body
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Edit Format

Important: The API endpoint parameters

  • PATH: /rest/v1/formats/{formatId}

EXAMPLE: https://app.etlworks.com/rest/v1/formats/1

  • METHOD: PUT
  • HEADER: Authorization:Bearer access-token
  • REQUEST BODY: JSON document in the following Format:
  • {
        "id": number, the ID
        "name": string, the name
        "description": string, the description
        "properties": object, the map of properties
        "tags": array, the list of tag strings
    }
  • REQUEST CONTENT TYPE: application/json.

Response

The response is a JSON document in the following Format:

{
    "id": number, the ID
    "name": string, the name
    "description": string, the description
    "formatType": string, the format type
    "properties": object, the map of properties
    "tags": array, the list of tag strings
}

Response Codes

  • 200 for success
  • 400 for the not valid request body
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Delete Format

Important: The API endpoint parameters

  • PATH: /rest/v1/formats/{formatId}

EXAMPLE: https://app.etlworks.com/rest/v1/formats/1

  • METHOD: DELETE
  • HEADER: Authorization:Bearer access-token
  • REQUEST BODY: none
  • REQUEST CONTENT TYPE: none
  • RESPONSE: none

Response Codes

  • 204 for success
  • 401 for not authorized
  • 403 for forbidden
  • 409 if the Format cannot be deleted because it is referenced in some Flow
  • 500 for an internal error

Related articles