Rest Endpoint Example

Disambiguation

The “Rest Connector” and the “Rest Endpoint Connector” are separate connection types.

  • Rest Connection (Not used in this example)
    • Hero_Flow is the active party that calls a REST API for getting or sending data.

    • A REST API is required (e.g. GET https://yourdomain/api/v1/users ) that can be called by Hero_Flow.

    • In the server-client terminology, Hero_Flow is the client for your server.

  • Rest Endpoint Connection

    • Hero_Flow is a passive party, that waits for REST API calls.

    • A client service is required that calls Hero_Flow’s API for sending or retrieving data.

    • In server-client terminology, Hero Flow is the server for your client.

  • Multiple REST Connections and Rest Endpoint Connections on the same Hero_Flow instance is supported.

Example Problem

You need to upload PDF files into Hero_Flow and store them so that another Flow can process them later.

Hero_Flow Setup

Publish a REST endpoint on the Hero_Flow side and store the uploaded files.

The Flow needs the following:

  • A File System Output. (For storing the uploaded file.)

  • A REST Endpoint Input. (For processing the API request with the file.)

  • A REST Endpoint Output. (For responding the API request.)

File System output

This example uses an SSH File System Output. It is your choice what Output fits into your use case.

REST Endpoint Connection

This example uses /api/pdf-upload for endpoint URL path. This path is needed later for the client setup.

REST Endpoint Input

The HTTP method and expected parameters can be configured. For a file upload, this configuration is a good example.

REST Endpoint Output

It’s important that the Connection and HTTP method matches the Input’s configuration. Response body mapping here is not necessary.

Automation Flow

The Flow in this example consists only of the Input and the two Outputs.

Important notes:

  • Schedule the Flow for to run "now". The Flow must run to accept REST API calls.

  • If the Flow has been modified, restart the Flow so it is up-to-date for the client.

  • If the Flow has been started or restarted, the Flow needs about 10 seconds before it can accept API calls.

  • The Flow starts with a REST Endpoint Input and has a corresponding REST Endpoint Output.

Testing the Flow Using Postman

At this point the Flow is ready to accept API calls and needs a client to call it. This call can be a script or program, service. This example uses Postman for demonstration.

  • First, the client is authenticated.

  • Then, the file(s) are upload using the /api/pdf-uploadendpoint. (Provided by the Flow.)

Authentication

For authentication A POST call is sent to {hero-flow-url}/api/authentication/login with the Basic Authentication header filled with a Hero_Flow user’s name and password.

The response Authorization header contains a JWT token. (A Refresh-Token header is also important, but its usage is out of the scope of this example.)

Important notes:

  • The generated JWT token is only valid for about 16 minutes. (This feature can be configured from hero_flow.conf)

  • Advanced, non-demo level solutions, require to refresh the JWT token periodically.

  • JWT tokens are sensitive information. They should be used carefully and not shared or saved.

Calling Hero_Flow's API

For calling Hero_Flow's API endpoint, a POST call is sent to {hero-flow-url}/api/pdf-upload (Remember, the example configured the Connection and Input to this HTTP Method and Endpoint URL.)

  • Add an Authorization header to the request with the returned JWT token. (Do not add Bearer to the value, just the token.)

  • The request body should be the file content.

The response code is 200 and the response body is an empty JSON.