Articles in this section

Call user-defined API

  • Updated
Follow
  • Startup
  • Business
  • Enterprise
  • On-Premise
  • Add-on

User-defined API endpoint

The endpoint URL is defined as https://etlworks_base_url/rest/v1/httplistener/url_pattern.

Example: https://app.etlworks.com/rest/v1/httplistener/patients

Read about the URL Pattern set for the Listener.

Authentication

User-defined API endpoints require authentication, using either a JWT token received from the authentication API or a username and password.

JWT Authentication

To configure an API endpoint with JWT authentication, in your HTTP Listener set Auth Type to JWT and Auth Location to either Header (recommended and more secure) or Query Parameter (less secure).

Calling user-defined REST API endpoints with JWT authentication

Step 1. Create an API user. 

You can actually use any user, as long as they have a required role (see below). API user can only be used to executed API endpoints created in Etlworks using Listeners.

Step 2. Use the user to call an Etlworks authentication endpoint and receive an access token.

Optionally, you can generate the non-expiring API key and use it as an access token in step 3. In this case, you can skip step 2 altogether. 

Step 3. Use the access token received in Step 2 to call Etlworks API endpoints.

If  Auth Location in your listener set to Header then access token must be sent in Authorization header parameter in Bearer access-token format (Example: Authorization:Bearer access-token).

If  Auth Location in your listener set to Query Parameter then access token must be set as a value of the Authorization query parameter in Bearer%20access-token format (Example: ?Authorization=Bearer%20access-token).

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. Alternatively, you can use the not-expiable API key as an access token. 

Basic Authentication

Generally speaking, basic authentication is less secure than JWT. Use it only if it is impossible to use two-step authentication. For example, this would be used when a third-party application has a simple webhook that sends a payload to the API.

To configure an API endpoint with Basic authentication, in your HTTP Listener set Auth Type to Basic and Auth Location to either Header (recommended and more secure) or Query Parameter (less secure).

Calling user-defined REST API endpoints with Basic authentication

Only APIs created in Etlworks using Listener can be configured to be authenticated with the basic authentication. All internal Etlworks's APIs require JWT authentication.

Step 1. Create an API user. 

You can actually use any user, as long as they have a role that can execute Flows.

Step 2. Use the username and password for the user created in Step 1 to create Basic authentication token. To create Basic authentication token Base 64 encode username:password. For example if your user name is admin and password is admin, then you need to Base 64 encode admin:admin which will become YWRtaW46YWRtaW4=.

Step 3. Use the Basic authentication token created in Step 2 to call Etlworks API endpoints.

If  Auth Location in your listener set to Header then access token must be sent in Authorization header parameter in Basic basic-auth-token format (Example: Authorization:Basic basic-auth-token).

If  Auth Location in your listener set to Query Parameter then access token must be set as a value of the Authorization query parameter in Basic%20basic-auth-token format (Example: ?Authorization=Basic%20basic-auth-token).

Read more about basic authentication.

Using basic auth as static part of the URL for authentication

One of the typical use-cases for user-defined API is integration with third-party webhooks. For example, you can create an API in Etlworks which will trigger a flow when something happened in a third-party system. You could then configure a webhook in that system so it would call a user-defined API created in Etlworks.

Many third-party services, for example eBay, implement a webhook system that does not allow configuring the callback URL with query parameters such as ?parameter=value, and does not support header parameters so you won't be able to configure a listener with authentication parameters sent in the header or query parameters.      

Here is a simple workaround: listener's Auth Type should be set to Basic and Auth Location to Query Parameter. Authentication string should be set as the last path parameter and it should be base 64 encoded like a standard Basic auth string.

For example, if your user account name and password are admin and admin, then:
  1. Base 64 encode username:password. admin:admin will become YWRtaW46YWRtaW4=
  2. Create standard Basic auth string by concatenating "Basic " and result from step 1. You will get Basic YWRtaW46YWRtaW4=
  3. Base 64 encode the result of step 2. You will get QmFzaWMgWVdSdGFXNDZZV1J0YVc0PQ==
  4. Add string obtained in step 3 to the end of the URL Pattern in the listener. Example:  some/example/path/QmFzaWMgWVdSdGFXNDZZV1J0YVc0PQ==. Alternatively, you can add a PATH parameter to the URL Pattern: some/example/path/{auth} . In both cases, you will need to wait one minute before the URL will become available. 
  5. Now you can use it as the last path parameter in the URL: /some/example/path/QmFzaWMgWVdSdGFXNDZZV1J0YVc0PQ==

Call user-defined API from Etlworks

Typically, the third-party application will be calling a user-defined API.

To execute a Flow without leaving Etlworks, you will need to create another Flow as a sender, as explained in this article.

Read how to call user-defined PULL API endpoint from the Etlworks Explorer.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.