API Actions

An API operation or query is built from API actions. These operations are mostly built automatically by the query builder component.

When you need to customise an operation or create your own, the best way is to create one or more custom actions and let the query builder inject it at the right place.

You can create custom actions on the API level, or for an API Edge.

API Actions

You can add API level actions by providing the actions directory for you API:

api.actionDir(`{__dirname}/actions`)

Every action in the specified directory will be automatically added to your API.

To create an action, just add a module to the actions directory similar to the following:

const { ApiAction, ApiActionTriggerKind } = require('api-core')
module.exports = new ApiAction(
    'example-action',
    scope => Promise.resolve(scope)),
    ApiActionTriggerKind.OnInput
)

Edge Actions

You can extend your edges with custom actions using the action method:

const { ApiActionTriggerKind } = require('api-core')
const edge = require('./edges/myEdge')
edge.action(
    'example-action',
    scope => Promise.resolve(scope)),
    ApiActionTriggerKind.OnInput
)

Creating actions

1. Placing the action in the pipeline

You can inject your action inside the operation pipeline by providing trigger parameters.

ApiEdgeActionTriggerKind

First, you have to specify whether to run the action before or after the triggered event using the ApiEdgeActionTriggerKind enum:

Enum value	Description
ApiEdgeActionTriggerKind.BeforeEvent	Run before the triggered event.
ApiEdgeActionTriggerKind.AfterEvent	Run after the triggered event.

ApiEdgeActionTrigger

Second, you have to specify the triggered event using the ApiEdgeActionTrigger enum:

Enum value	Description
ApiEdgeActionTrigger.OutputQuery	The last query in the pipeline, which generates the original output of the operation.
ApiEdgeActionTrigger.SubQuery	Any query in the pipeline, except the output query.
ApiEdgeActionTrigger.Query	Any query in the pipeline.
ApiEdgeActionTrigger.Method	Custom method(s) identified by the triggerNames parameter.
ApiEdgeActionTrigger.Relation	Relation(s) identified by the triggerNames parameter.
ApiEdgeActionTrigger.Any	Any of the previous options, maybe identified by the triggerNames parameter.

ApiEdgeQueryType

Third, you have to specify which query types to trigger using the ApiEdgeQueryType enum:

Enum value	Description
ApiEdgeQueryType.List	A read query which results in a list of entries.
ApiEdgeQueryType.Get	A read query which results in a single entry.
ApiEdgeQueryType.Create	A create query.
ApiEdgeQueryType.Update	An update or edit query.
ApiEdgeQueryType.Patch	A replace query.
ApiEdgeQueryType.Delete	A delete query.
ApiEdgeQueryType.Exists	A read query for checking whether a specified entry exists.
ApiEdgeQueryType.Change	An Update or Replace query.
ApiEdgeQueryType.Read	A Get or List query.
ApiEdgeQueryType.ReadOrChange	A Get, List, Update or Patch query.

2. The execution scope

is quite complicated. :/