API

Label: :IA_Function
Property: type: API
Inherits from: Function

Creates an API endpoint, that can be called from outside Graphileon, or from visual components.

Parameters

Key	Description	Default value	Possible values
`end`	Close connection after response is sent. Set this to `false` (initially) when streaming multiple responses until the last response is sent then set to `true` to close the connection.	`true`	`true`/`false`
`error`	When set (for the first time), the API Function will return the given value as an error to the caller.		string
`headers`	Response headers	null	Object as valid JSON string (without `evaluate()`)
`input`	Request input data. Set automatically when the request is made. Contains request body, query parameters and route parameters, but not request headers.	`{}`	Object
`method`	HTTP Method to which the API Function will respond.	`post`	`get` / `post` / `put` / `patch` / `delete`
`response`	Response of the request. When updated, the API Function returns its value as response to the caller.		`String`/`Object`/`Array`
`status`	HTTP response code	200	`Number`
`timeout`	Time in milliseconds to wait for a response (update trigger). The timeout is reset after each `response` update (when streaming)	60000 (one minute)	`Number` / `null`

* The public parameter can only be set directly on the Function, and can only have a static value (true or false). It cannot be set from an incoming Trigger, nor evaluated based on dynamic data (e.g. (@)).

Note: in the Trigger that sets the response, $_instance should be set to (%)._path.apiInstance (see Example Usage).

Outgoing triggers

Type: `request`

Occurrence: When the API endpoint gets requested.

Additional event properties (besides the inherited properties):

Key	Description	Possible values
`input`	The input provided to the API request. Contains request body, query parameters and route parameters.	object
`headers`	The incoming HTTP request headers. Header names are typically lowercase.	object

Example usage

An API endpoint is created by an :IA_Function node with type: API and iaName properties, e.g.:

{
	"type": "API",
	"iaName": "my-api"
}

The API endpoint can then be called from outside Graphileon using the following url pattern:

http{s}://{domain}:{port}/api/app/my-api?myInput=myInputValue

Input can be provided both by url parameters (myParam=myValue) and request body (for methods other than GET).

The API endpoint can also be used from a visual component inside Graphileon, e.g. (an Html component):

<ia-api ia-name="my-api" input-myInput="myInputValue"></ia-api>

Both approaches will call the my-api endpoint, executing the API node above. The API Function will then fire a request trigger with

{
	"type": "request",
	"input": {
		"myInput": "myInputValue"
	},
	"headers": {
		"x-my-header": "myHeaderValue"
	}
}

So inside the execution chain:

use (%).input for request body, query parameters and route parameters
use (%).headers for incoming HTTP headers, for example (%).headers["authorization"]

The request headers are exposed separately, so they are not merged into (%).input.

Now, a whole chain of Functions can be executed to get the desired result, which should then be fed back to the API node with a trigger containing a $response parameter and an $_instance parameter, e.g.:

{
	"type": "someTriggerType",
	"$response": "My Final Response Value",
	"$_instance": "(%)._path.apiInstance"
}

Note: Behind the screens, the API Function is executed with a unique instance ID, which is stored in _path.apiInstance during the API execution chain. The final Trigger containing the response will then have to update the original API instance. The parameter "$_instance": "(%)._path.apiInstance" therefore needs to be present in this Trigger.

When the original API Function gets updated, it causes the response to be given back to the caller and, in this case, the value of $response will then be the response to the request, or for visual components, filled into the <ia-api> html component.

Request authentication

Public enpoints

By default, all API endpoints are restricted to authenticated users. So before using an API endpoint the user must login into the application.

To create a public endpoint, the API Function should have a public: true property, as well as all the Functions in its execution chains. This allows the API and all involved Functions to be loaded from the database without authentication.

User token authentication

To make an authenticated request to an API endpoint, the user should be connected to an IA_Token node by USES relation. The IA_Token node should have a token property with a long random string, and a purpose: api property to designate it as an API token.

Expected pattern:

	(:IA_User)-[:USES]->(:IA_Token {purpose: `api`, token: `<random-string>`})

Then, an authenticated request (without previous user login) can be made by including the token.

Example for GET request:

https://my-graphileon.com/api/app/my-endpoint?token=j2hb288fbb26gf3790sfsghnhfs773g110cbbhg

The token can also be sent through the api-token HTTP header. Example (raw HTTP request):

GET /api/app/my-endpoint HTTP/1.1
Accept: ...
.....
API-Token: j2hb288fbb26gf3790sfsghnhfs773g110cbbhg
...

For Dashboard Designers Reference API

API