Integrations and APIs

Whether you want to built event-driven data integration flows or incorporate Integrator into your own automation workflow, you can use the developer features below to achieve your goals.

Calling Integrator API endpoints

Step 1. Create an API user.

Step 2. Use API user to call Integrator authentication endpoint and receive an access token.

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

Important: access tokens in Integrator are short-lived and self expiring. Access token gives you an access to the APIs for approximately 10 minutes. It is recommend to refresh access token before each call to the API.

Authentication API

This API must be used to receive an access token, giving third party application temporary access to the open Integrator APIs.

PATH: /rest/v1/token-auth/issue

EXAMPLE: http://integrator.etlworks.com/rest/v1/token-auth/issue

METHOD: POST

REQUEST BODY: {"login":"{user}","password":"{password}"}, where {user} is a user id of the API user and {password} is a password for the API user.

REQUEST CONTENT TYPE: application/json

RESPONSE: {"token": "access token"}, where "access token" is an actual access token which will be used for all authenticated requests to the API.

RESPONSE CODES: 200 for success, 401 and 403 for not authorized, 500 for internal error

Event-driven flows

The Integrator can be used as an Enterprise Service Bus, serving requests from the third-party applications. Basically you can build an API, without writing a single line of code, which can be used by other applications to send payload to the Integrator.

Below is a typical example of the event-driven flow:

  1. Third party application updates it's own database.
  2. Update triggers event, which sends a notification to the Integrator and includes updated record(s) as a part of the payload.
  3. There is an HTTP listener, configured in the Integrator, which listens to the incoming HTTP requests.
  4. There is also a flow, which has a listener as a source (FROM) connection. The flows is scheduled and ready to receive a payload.
  5. Once payload is received, Integrator automatically executes flow and passes payload as a source.
  6. The source is getting transformed to the destination. For example information about updated record(s) is sent to the data warehouse.

Read more about event-driven flows.

Listeners

Listeners are a special type of the Integrator's connectors that allow user to create event-driven flows. For example, you can define an HTTP endpoint which will be listening to the incoming HTTP POST requests. Once request is received, the payload will be send to the flow as a source and transformed to any supported destination.

Read more about available listeners.

HTTP Listener API

This API allows developer to create user-defined endpoints, receiving payload from the third party applications and triggering execution of the Integrator flows.

PATH: /plugins/schedules/rest/v1/httplistener/{user-defined-path}

EXAMPLE: http://integrator.etlworks.com/plugins/schedules/rest/v1/httplistener/hl7/patient, where /hl7/patient is a user-defined-path, defined when creating http listener.

METHOD: POST

HEADER: Authorization:Bearer access-token

REQUEST BODY: a payload in any of the supported formats, such as CSV, XML and JSON.

REQUEST CONTENT TYPE: not required.

RESPONSE: a response defined by the developer, typically json document.

RESPONSE CODES: 200 for success, 401 and 403 for not authorized, 500 for internal error

Executing Integrator flows on demand from your application

You can incorporate Integrator into your own automation workflow by delegating heavy-duty integration tasks and executing flows on demand.

Run flow by name API

PATH: /plugins/flows/rest/v1/flows/flow-name/{flowName}/run

EXAMPLE: http://integrator.etlworks.com/plugins/flows/rest/v1/flows/flow-name/my-flow/run, where my-flow is a name of the flow to execute.

METHOD: POST

HEADER: Authorization:Bearer access-token

REQUEST BODY: none.

REQUEST CONTENT TYPE: none.

RESPONSE: {"status":status-code,"exception":"exception-stack-trace"}. Possible status codes: 0 - success, 1 - error

RESPONSE CODES: 200 for success, 401 and 403 for not authorized, 500 for internal error

Querying Integrator audit-trail log

Each event, such as login, flow execution, etc. is captured in the Integrator audit-trail log. To retrieve last 1000 events use the following endpoint.

Important: to access this API you must use admin user for the authorization request.

PATH: /plugins/audit/rest/v1/audit

EXAMPLE: http://integrator.etlworks.com/plugins/audit/rest/v1/audit

METHOD: GET

HEADER: Authorization:Bearer access-token

REQUEST BODY: none.

REQUEST CONTENT TYPE: none.

RESPONSE: JSON document

RESPONSE CODES: 200 for success, 401 and 403 for not authorized, 500 for internal error