User-defined APIs

Basics

The core element of the infrastructure, which allows one to build REST APIs in Integrator, is the HTTP listener. The HTTP listener is a special type of connector that is constantly listening to incoming HTTP requests, using a configurable PATH and METHOD.

Depending upon which side of the transformation (source or destination) the HTTP listener sits, it can either push payload to the flow or return a response to the client.

Read more about event-driven flows.

User-defined API

A user-defined API allows the developer to create custom endpoints, which can receive payloads from third-party applications, triggering execution of Integrator's flows.

• PATH: /rest/v1/httplistener/{user-defined-path}.

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

• METHOD: POST,PUT,GET,DELETE.
• HEADER: Authorization:Bearer access-token.
• REQUEST BODY: a payload in any of the supported formats, such as CSV, XML or JSON. The payload is not required.
• REQUEST CONTENT TYPE: not required.
• RESPONSE (GET): a response defined by the developer, typically a JSON document.
• RESPONSE (PUSH and PUT): a pre-defined response or response defined by the developer, typically a JSON document.
• RESPONSE (DELETE): a pre-defined response.
• RESPONSE CODES: 200 for success, 401 and 403 for not authorized, and 500 for an internal error.

Pre-defined response (example)

{
 "auditId": 106358,
 "messageUuid": "caaa8347-063c-449b-a29b-12e68799c986",
 "flowId": 3219,
 "status": "success"
}

Examples

Below are the typical examples of the user-defined APIs.

PULL: expose a data source as an API endpoint

1. The flow is configured and scheduled in Integrator to receive GET requests, pull the data from any source, transform, and save into the HTTP listener (response).
2. The third-party application, for example, Tableau makes a call to the API endpoint created in Integrator to pull the enriched dataset.

Read about PULL API.

PUSH: when API endpoint receives a payload it triggers the execution of a data integration flow

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

Read about PUSH API.