Rest Endpoint Example
Disambiguation
The “Rest Connector” and the “Rest Endpoint Connector” are separate connection types.
- Rest Connection (Not used in this example)
Hero Platform_ 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 Platform_.
In the server-client terminology, Hero Platform_ is the client for your server.
Hero Platform_ is a passive party, that waits for REST API calls.
A client service is required that calls Hero Platform_'s API for sending or retrieving data.
In server-client terminology, Hero Platform_ is the server for your client.
Multiple REST Connections and Rest Endpoint Connections on the same Hero Platform_ instance is supported.
Example Problem
You need to upload PDF files into Hero Platform_ and store them so that another Flow can process them later.
Hero Platform_ Setup
Publish a REST endpoint on the Hero Platform_ 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 Platform_ 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 Platform_.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 Platform_'s API
For calling Hero Platform_'s API endpoint, a POST call is sent to {hero-platform-url:port number}/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.
- Port number 8081
The response code is 200 and the response body is an empty JSON.
