Articles in this section

See more

Flows management API

  • Updated
Follow

Overview

This API is used to query, add, edit, delete, stop, suspend and resume Flows. 

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 in calling Etlworks authentication endpoint and receiving 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.

Get All Flows

Important: The API endpoint parameters

  • PATH: /rest/v1/flows

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

  • METHOD: GET
  • HEADER: Authorization:Bearer access-token

Response

The response is a JSON document in the following Format:

[
    {
        "id": number, (the flow ID)
        "name": string, (the flow name)
        "description": string, (the flow description)
        "flowType": string, (the flow type)
        "properties": object, (the global flow properties)
        "transformations": array, (the list of transformation objects)
        "mappings": array, (the list of mapping objects)
        "connections": array, (the list of connection objects)
        "nestedFlows": array, (the list of nested flows)
        "tags": array, (the list of tag strings)
    }
]

Response Codes

  • 200 for success
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Get Flow By ID

Important: The API endpoint parameters

  • PATH: /rest/v1/flows/{flowId}

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

  • METHOD: GET
  • HEADER: Authorization:Bearer access-token

Response

The response is a JSON document in the following Format:

{
    "id": number, (the flow ID)
    "name": string, (the flow name)
    "description": string, (the flow description)
    "flowType": string, (the flow type)
    "properties": object, (the global flow properties)
    "transformations": array, (the list of transformation objects)
    "mappings": array, (the list of mapping objects)
    "connections": array, (the list of connection objects)
    "nestedFlows": array, (the list of nested flows)
    "tags": array, (the list of tag strings)
}

Response Codes

  • 200 for success
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Add new Flow

Important: The API endpoint parameters

  • PATH: /rest/v1/flows

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

  • METHOD: POST
  • HEADER: Authorization:Bearer access-token
  • REQUEST BODY: JSON document in the following Format. The actual payload has hundreds of permutations. Contact Etlworks support for more details.
  • {
        "name": string, (the flow name)
        "description": string, (the flow description)
        "flowType": string, (the flow type)
        "properties": object, (the global flow properties)
        "transformations": array, (the list of transformation objects)
        "mappings": array, (the list of mapping objects)
        "connections": array, (the list of connection objects)
        "nestedFlows": array, (the list of nested flows)
        "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 flow ID)
    "name": string, (the flow name)
    "description": string, (the flow description)
    "flowType": string, (the flow type)
    "properties": object, (the global flow properties)
    "transformations": array, (the list of transformation objects)
    "mappings": array, (the list of mapping objects)
    "connections": array, (the list of connection objects)
    "nestedFlows": array, (the list of nested flows)
    "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 Flow

Important: The API endpoint parameters

  • PATH: /rest/v1/flows/{flowId}

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

  • METHOD: PUT
  • HEADER: Authorization:Bearer access-token
  • REQUEST BODY: JSON document in the following Format. The actual payload has hundreds of permutations. Contact Etlworks support for more details.
  • {
        "id": number, (the flow ID)
        "name": string, (the flow name)
        "description": string, (the flow description)
        "properties": object, (the global flow properties)
        "transformations": array, (the list of transformation objects)
        "mappings": array, (the list of mapping objects)
        "connections": array, (the list of connection objects)
        "nestedFlows": array, (the list of nested flows)
        "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 flow ID)
    "name": string, (the flow name)
    "description": string, (the flow description)
    "flowType": string, (the flow type)
    "properties": object, (the global flow properties)
    "transformations": array, (the list of transformation objects)
    "mappings": array, (the list of mapping objects)
    "connections": array, (the list of connection objects)
    "nestedFlows": array, (the list of nested flows)
    "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 Flow

Important: The API endpoint parameters

  • PATH: /rest/v1/flows/{flowId}?optional_parameters

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

  • METHOD: DELETE
  • HEADER: Authorization:Bearer access-token
  • PARAMETERS:

connections=true.  Boolean, if true delete all Connections/Formats referenced by this Flow, but not referenced by other Flows. Default: false.

schedules=true. Boolean, if true delete all schedules for this Flow. Default: false.

  • REQUEST BODY: none
  • REQUEST CONTENT TYPE: none

Response

The response is a JSON document in the following Format:

{
    "flowId": number, (the flow ID)
    "status": string, (the status of request)
    "flows": array, (the list of flow reference objects)
    "schedules": array, (the list of schedule reference objects)
    "agents": array, (the list of agent reference objects)
    "connections": array, (the list of connection reference objects)
    "formats": array, (the list of format reference objects)
    "message": string, (exception details in case status is error)
}

Response Codes

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

Stop Flow execution

Important: The API endpoint parameters

  • PATH: /rest/v1/flows/{flowId}/stop

EXAMPLE: https://app.etlworks.com/rest/v1/flows/1/stop

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

Response

The response is a JSON document in the following Format:

{
    "status": string (the status of request)
}

Response Codes

  • 200 for success
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Suspend Flow executions

Suspends executions of all Flows in the instance. Optionally stops all currently running Flows. 

Important: The API endpoint parameters

  • PATH: /rest/v1/system/suspend?stopFlows=false

EXAMPLE: https://app.etlworks.com/rest/v1/system/suspend

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

Response Codes

  • 200 for success
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Resume Flow executions

Resumes executions of all Flows in the instance.  

Important: The API endpoint parameters

  • PATH: /rest/v1/system/resume

EXAMPLE: https://app.etlworks.com/rest/v1/system/resume

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

Response Codes

  • 200 for success
  • 401 for not authorized
  • 403 for forbidden
  • 500 for an internal error

Related articles