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.

• API

  • Parameters

  • Outgoing triggers

    • Type: request

  • Example usage

  • Request authentication

    • Public enpoints

    • User token authentication

Parameters

Key	Description	Default value	Possible values
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())
method	HTTP Method to which the API Function will respond.	post	get / post / put / patch / delete
response	When set (for the first time), the API Function returns its value as response to the caller.		any

* 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.	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"
	}
}

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
...