Skip to content
This page View Markdown Open in ChatGPT Open in Claude

Events and listeners

An event is a name with listeners : functions which run when the event is emitted, each in the language it was written in. Your code emits it, a client emits it through the system API, or API Maker emits it on its own after an API you attach it to. Events keep the side effects of an operation (mails, stock, notifications, exports) out of the API which triggers them.

Events : emitted by code, by the system API or after an API hit, with N listeners, and no infinite loops who emits An API hit automatic trigger, after the API Your code g.sys.system.emitEvent(…) System API POST …/emit-event Event order-placed eventData travels with it listeners · your functions send-invoice g.req.eventData · timeout in minutes update-stock runs in the sandbox notify-warehouse emits another event warehouse-sync another event, its own listeners back to an event already running : stopped, no infinite loop The emitter gets the output of every listener back : { listenerName, output } Listeners run one after the other, with the log profile recording each run.

Create an event

APIs & Logic → Events, then +.

Field Meaning
Name The name used to emit it. Unique in the account.
Automatically trigger on API hit On : the event is emitted after every successful call of the APIs listed under it.
Trigger on APIs Instance APIs (an API of a table), custom APIs, system APIs. Several at once.
Listeners One or more, each with a name, a code and its language, a timeout in minutes, versions, and runOnNativeProcess.
Save response in log Keep what the listeners returned in the log table.

A listener

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import * as T from 'types';
import * as db from 'db-interfaces';

async function main(g: T.IAMGlobal) {
    const data = g.req.eventData;   // what was emitted
    await g.sys.db.saveSingleOrMultiple({
        instance: 'mongodb', database: 'shop', collection: 'notifications',
        saveData: { order_no: data.order_no, text: `Order ${data.order_no} placed` },
    });
    return { notified: true };      // returned to the emitter
}
module.exports = main;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from am import G


async def main(g: G):
    data = g.req.event_data   # what was emitted
    await g.sys.db.save_single_or_multiple(
        'mongodb', 'shop', 'notifications',
        save_data={'order_no': data.order_no, 'text': f'Order {data.order_no} placed'},
    )
    return {'notified': True}  # returned to the emitter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?php
function main(AmG $g)
{
    $data = $g->req->eventData;   // what was emitted
    $g->sys->db->saveSingleOrMultiple(
        'mongodb', 'shop', 'notifications',
        saveData: ['order_no' => $data->order_no, 'text' => "Order {$data->order_no} placed"],
    );
    return ['notified' => true];  // returned to the emitter
}

1
2
3
4
5
6
7
8
9
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        var orderNo = g.Req.EventData?["order_no"]?.GetValue<long>();   // what was emitted
        await g.Sys.Db.SaveSingleOrMultiple(new Save("mongodb", "shop", "notifications", new { order_no = orderNo, text = $"Order {orderNo} placed" }));
        return new { notified = true };  // returned to the emitter
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
package code

import (
    "fmt"

    "apimaker/am"
)

func Main(g *am.G) (any, error) {
    data := am.AsM(g.Req.EventData()) // what was emitted
    _, err := g.Sys.Db.SaveSingleOrMultiple(am.Save{
        Instance: "mongodb", Database: "shop", Collection: "notifications",
        SaveData: am.M{"order_no": data.Get("order_no"), "text": fmt.Sprintf("Order %v placed", data.Get("order_no"))},
    })
    if err != nil {
        return nil, err
    }
    return am.M{"notified": true}, nil // returned to the emitter
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
use am::{Errors, G, Save, Value, json};

pub fn main(g: &mut G) -> Result<Value, Errors> {
    let order_no = g.req.event_data()["order_no"].clone(); // what was emitted
    g.sys.db.save_single_or_multiple(Save::new(
        "mongodb",
        "shop",
        "notifications",
        json!({ "order_no": order_no, "text": format!("Order {order_no} placed") }),
    ))?;
    Ok(json!({ "notified": true })) // returned to the emitter
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import am.G;
import am.JsonObject;
import am.Save;
import java.util.Map;

class Api {
    static Object main(G g) {
        JsonObject data = JsonObject.from(g.req.getEventData());   // what was emitted
        g.sys.db.saveSingleOrMultiple(new Save("mongodb", "shop", "notifications",
            Map.of("order_no", data.getLong("order_no"), "text", "Order " + data.getLong("order_no") + " placed")));
        return Map.of("notified", true);  // returned to the emitter
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import am.G
import am.JsonObject
import am.Save

fun main(g: G): Any? {
    val data = JsonObject.from(g.req.eventData)   // what was emitted
    g.sys.db.saveSingleOrMultiple(
        Save("mongodb", "shop", "notifications", mapOf("order_no" to data.getLong("order_no"), "text" to "Order ${data.getLong("order_no")} placed")),
    )
    return mapOf("notified" to true)  // returned to the emitter
}
  • Every listener gets the same g as a custom API : g.req.eventData holds the emitted data, g.sys reaches every API, g.logger writes to the log table.
  • Listeners run one after the other, each within its timeout : in the sandbox and with runOnNativeProcess alike. Empty : sandboxReqTimeout of the configuration (13 seconds), whatever time the request which emitted the event has.
  • For an automatic trigger, g.req.eventData is the whole answer of the API which triggered it ({ success, statusCode, data, … }), so a listener sees what was saved or read.

Emit from your code

1
2
3
4
const result = await g.sys.system.emitEvent('order-placed', { order_no: 1001, customer_id: 42 });
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

await g.sys.system.emitEvent('order-placed', { order_no: 1001 }, [ 'send-invoice' ]);   // only these listeners

1
2
3
4
result = await g.sys.system.emit_event('order-placed', {'order_no': 1001, 'customer_id': 42})
# result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

await g.sys.system.emit_event('order-placed', {'order_no': 1001}, ['send-invoice'])  # only these listeners

1
2
3
4
$result = $g->sys->system->emitEvent('order-placed', ['order_no' => 1001, 'customer_id' => 42]);
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

$g->sys->system->emitEvent('order-placed', ['order_no' => 1001], ['send-invoice']); // only these listeners

1
2
3
4
var result = await g.Sys.System.EmitEvent("order-placed", new JsonObject { ["order_no"] = 1001, ["customer_id"] = 42 });
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

await g.Sys.System.EmitEvent("order-placed", new JsonObject { ["order_no"] = 1001 }, ["send-invoice"]); // only these listeners

1
2
3
4
5
6
7
8
9
result, err := g.Sys.System.EmitEvent("order-placed", am.M{"order_no": 1001, "customer_id": 42})
if err != nil {
    return nil, err
}
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

if _, err := g.Sys.System.EmitEvent("order-placed", am.M{"order_no": 1001}, "send-invoice"); err != nil { // only these listeners
    return nil, err
}

1
2
3
4
let result = g.sys.system.emit_event("order-placed", json!({ "order_no": 1001, "customer_id": 42 }), &[])?;
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

g.sys.system.emit_event("order-placed", json!({ "order_no": 1001 }), &["send-invoice"])?; // only these listeners

1
2
3
4
var result = g.sys.system.emitEvent("order-placed", Map.of("order_no", 1001, "customer_id", 42));
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

g.sys.system.emitEvent("order-placed", Map.of("order_no", 1001), List.of("send-invoice")); // only these listeners

1
2
3
4
val result = g.sys.system.emitEvent("order-placed", mapOf("order_no" to 1001, "customer_id" to 42))
// result.outputArr : [ { listenerName: 'send-invoice', output: { notified: true } }, … ]

g.sys.system.emitEvent("order-placed", mapOf("order_no" to 1001), listOf("send-invoice")) // only these listeners
  • The third argument names the listeners to run ; absent, every listener runs.
  • The emitter gets the output of each listener back, so an event can also be a way to run several pieces of code and collect their results.

Emit over HTTP

POST /api/system-api/admin/emit-event

{ "name": "order-placed", "eventData": { "order_no": 1001 }, "executeListeners": [ "send-invoice" ] }
  • An array of such objects emits several events in one call. See Emit event.

Chains without loops

A listener may emit another event, which may emit another. API Maker keeps the list of the events already running for the request : an emit which comes back to one of them is stopped, so a chain never becomes an infinite loop. Each level of depth is allowed ; only the cycle is refused.

Where it fits

Need Use
Something must happen after an API, in code An event with an automatic trigger, or a post hook when it must change the answer
A client must be told live A WebSocket event, emitted with emitEventWS
Something must happen on a schedule A scheduler

Good to know

  • Events and their listeners are files in Git and deploy with a pull. Listeners have versions.
  • Test a listener from the API testing page : pick the event, the listener, put the event data in the body and send.
  • On the Events page, Move up and Move down order the listeners, Grid View lists every listener of every event, Clone copies an event with its listeners and Copy full event name gives the name to emit.
  • On the native process, console.log is not captured : use g.logger.
  • A log profile records each listener run.
  • Groups grant events : an API user needs a group with the event to emit it through the system API.