Custom routes

APIO core supports custom HTTP routes. You can use them to expose your workflows to create your own API calls.

Page: /transactions/config/startup_events

Definition

Attribute	Description
Route	The path of the route.
Method	The HTTP method of the route.
Group	The group of the route.
JSON Schema	The request body can be validated with a JSON schema before launching the workflow.
Output JSON Schema	The response body can be described for the OpenAPI generator.
Error handler	The workflow to launch when a blocking error occurs (see here).
Enabled	The route is enabled.
Sync	The route is synchronous (see here).
Public	The route does not require authentication.
Support bulk	The route supports bulk requests.
Bulk options	The options of the bulk requests.

Synchronous vs Asynchronous routes

The custom routes can be synchronous or asynchronous. The synchronous routes are executed in the same thread as the HTTP request. The asynchronous routes are executed in a separate thread.

The synchronous routes are useful when the workflow is fast. The asynchronous routes are useful when the workflow is slow or long-running. In this case, the workflow can be launched in a separate thread and the HTTP request can be closed. The workflow can continue to run in the background.

When the route is asynchronous, the response is sent immediately. The response contains the ID and the GUID of the transaction. The transaction can be used to track the status of the workflow. (via the API GET /api/v01/transactions/{id} or via the UI /transactions/{id})

Error handler

The error handler is a workflow that is executed when a blocking error occurs. You can see that as a try/catch mechanism.

It receives a {request} containing the following attributes:

Attribute	Description
instance	the top parent instance
context	the top parent context
request	the initial request received by the custom route
errors	the list of errors attached to the top parent instance

In case of a synchronous route, the error handler is executed before sending the response. So the response can be customized based on the error. When the error workflow completes succesfully, the context keys *response* and *cb_response* are moved from the error handler instance to the top parent instance, and then used to build the response.

In case of an asynchronous route, the error handler can be used to send a notification or a callback to the user or to the administrator.

Asynchronous response sample

{
    "id": 1,
    "guid": "70195486-8934-4a31-a504-a97a72c7f322"
}

Synchronous response

When the route is synchronous, the response is sent when the workflow reach an end node. The response is evaluated based on the context key *response* (set with a context setter node for instance).

The value has to be a JSON object with the following attributes:

Attribute	Description
status	The HTTP status code of the response.
body	The body of the response. It can be a string or a JSON object.
headers	A JSON object with the headers to be added in the response.

TIP

Because there is a match in the structure of the output of http call nodes and the structure of the response of the custom routes, the http call nodes can output directly in the *response* context key without further processing.

TIP

If the *response* value is not a valid JSON object, the workflow can be closed succesfully but the response will have a status 500 (Internal Server Error).

Samples Response

Description	Value of *response* key	Response
JSON response	{ "status": 200, "body": { "message": "hello, world" } }	HTTP/1.1 200 OK Content-Type: application/json { "message": "hello, world" }
Plain response	{ "status": 200, "body": "hello, world" }	HTTP/1.1 200 OK Content-Type: text/plain hello, world
File attachment response	{ "status": 200, "body": "hello, world", "headers": { "content-disposition": "attachment; filename=\"hello.txt\"", "content-type": "text/plain" } }	HTTP/1.1 200 OK Content-Type: text/plain Content-Disposition: attachment; filename="hello.txt" hello, world

Downloadable file

If the workflow build up a file (e.g csv, Excel etc...) and the response has to be a downloadable file, the context key *doc_response* has to be set with the filename of the file built by the workflow.

The status code of the response is set to 200 (OK) and the content type is set to the MIME type of the file.

For the interest of the reader, here a basic workflow definition that builds a CSV file and returns it as a downloadable file.

{
	"cells": {
		"start": {
			"original_name": "start",
			"outputs":       ["ok"]
		},
		"a": {
			"original_name": "create_csv",
			"params": {
				"filename":   "doc1.csv",
				"inputs": "[[\"hello\", \"world\"], [\"foo\", \"bar\"]]"
			},
			"outputs": ["ok"]
		},
		"b": {
			"original_name": "context_setter",
			"params": {
				"key":   "*doc_response*",
				"value": "doc1.csv"
			},
			"outputs": ["ok"]
		},
		"end": {
			"original_name": "end"
		}
	},
	"transitions": [
		["start.ok", "a"],
		["a.ok", "b"],
		["b.ok", "end"]
	]
}

Authenticated routes

By default, all custom routes are authenticated. The authentication is done using the JWT token. The JWT token is added to the Authorization header (Bearer authentication scheme) of the HTTP requests.

Such routes are exposed under the /api/v01/custom path. For example, the route /my-route is exposed as https://api.example.com/api/v01/custom/my-route.

Public routes

The custom routes can be public. In this case, they do not require authentication. Such routes are exposed under the /api/v01/public path. For example, the route /my-route is exposed as https://api.example.com/public/my-route.

Public routes are useful when you want to expose your workflows to external systems in a secure environment. (e.g. a private network or health check)

Proxied routes

APIO core can be deployed with one or several proxies to intercept and/or forward some traffic to a Broadsoft gateway (Netaxis product). In this case, the proxy process will use the custom routes to overload or extend the Broadsoft gateway API calls.

Proxied routes are usually exposed under the /api/v01/p{id} path. For example, the route /my-route is exposed as https://api.example.com/api/v01/p1/my-route.

All proxied routes require the user to be authenticated.

WARNING

Proxied routes (not overloaded by custom routes) are executed with different user sessions depending of the originating user:

• The user is a Broadsoft user, the route is executed with the user session.
• The user is an APIO user, the user profile is used to allow or deny the execution of the route. If the user profile is allowed to execute the route, the route is executed with the system level session.

There is no risk of impersonation because the user session is always used for Broadsoft users.

Some nodes are especially usefull in the context of the proxied routes, e.g. Proxy user session node, to use the user session to make calls to the Broadsoft gateway.

API documentation

The Broadsoft gateway API is described here.

WARNING

The documentation mention paths with a prefix /api/v1 but ther are exposed under the /api/v01/p{id} path on the proxy.

e.g /api/v1/tenants/ is exposed at /api/v01/p{id}/tenants/.

Documentation

The custom routes are documented in the OpenAPI generated specification. The specification is available at the /api/v01/custom_routes.swagger.yml path. For example, https://api.example.com/api/v01/custom_routes.swagger.yml.