Calling your APIs
The Program Calls, Data APIs and RPA Calls that you define in the Hub are called Functional APIs. Any REST client can call them, for example cURL, Postman or your application. This page shows the addresses, the authentication and sample requests. To configure the APIs, use the Admin API or the web UI.
Addresses
| API type | Address | Methods |
|---|---|---|
| Program Call | http://<hub-host>:8080/<uri> |
The HTTP verbs set in the definition |
| Data API | http://<hub-host>:8080/<uri> |
The HTTP verbs set in the definition (GET, POST, PUT, PATCH, DELETE) |
| RPA Call | http://<hub-host>:8080/rpa/<uri> |
The HTTP verbs set in the definition |
<uri> is the URI of the API definition. The Hub also accepts the same address with the prefix /api, for example /api/<uri>. Use https and the HTTPS port when you have set up HTTPS. You can also call an RPA Call directly on the RPA Hub, see RPA Hub user guide.
An inactive API returns 404. See Managing Hub APIs.
Authentication
By default, the Functional APIs use HTTP Basic authentication. Send the credentials of the Functional API user, or of an administrator:
With cURL, use the option -u <user>:<password>. The distribution asks for the user IDs and passwords in the first-launch wizard, see Security hardening.
If you enabled OAuth for the Hub, send a token that your provider issued:
See OAuth configuration.
Users that you create with the Admin API can run only the APIs that their User Groups permit. Without the permission, the Hub returns 403. See User groups and permissions.
Send the header Content-Type: application/json with every request that has a body.
Where the values go
The Hub reads the value of each API parameter from the JSON body, the query string, the headers or the URI. The Source field name of the parameter decides which. See API parameters configuration.
Examples
The examples use placeholders. Replace <user>, <password>, <hub-host> and the URIs with your own values.
Program Call with a JSON body
curl -u <user>:<password> \
-H "Content-Type: application/json" \
-d '{"orderID": 12345, "orderLines": 1, "orderItemsIn": [{"item": "ITEM1", "qty": 123.45, "price": 321.45}]}' \
http://<hub-host>:8080/custom/uri
Program Call with query parameters
A structure or an array in a query string uses dots for nested values and _0, _1 and so on for array items:
curl -u <user>:<password> \
"http://<hub-host>:8080/custom/uri?orderID=12345&orderLines=1&orderItemsIn_0.item=ITEM1&orderItemsIn_0.qty=123.45&orderItemsIn_0.price=321.45"
Value from the URI and from the body
For an API with the URI orders/{orderId} and the verb PATCH, map the parameter orderId to message.uriParams.orderId and the parameter status to the body field status:
curl -u <user>:<password> -X PATCH \
-H "Content-Type: application/json" \
-d '{"status": "SHIPPED"}' \
http://<hub-host>:8080/orders/12345
Data API
A Data API with a SELECT statement returns the rows in data and the paging details in meta. Use limit and offset to read the result page by page, see Data API configuration:
{
"status": "OK",
"data": [
{ "CUSTOMER_ID": 1, "STATUS": "ACTIVE" }
],
"meta": { "limit": 10, "offset": 0, "total": 1, "affectedRows": 1 }
}
RPA Call
curl -u <user>:<password> \
-H "Content-Type: application/json" \
-d '{"orderId": "1042"}' \
http://<hub-host>:8080/rpa/orders/status
The response contains the values that the RPA Call read from the screen, see Response.
Errors
| Status | Cause |
|---|---|
400 |
The request is not valid, for example when request validation is on and a value is wrong. The message lists the problems |
401 |
The credentials are missing or wrong |
403 |
The user has no permission for this API |
404 |
The API does not exist or is inactive |
Try it without code
You can call an API from the web UI, see Executing APIs. Each API also has an OpenAPI specification that you can import into Postman or Swagger tools, see Managing Hub APIs.