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

Post hooks

A post hook is a function of yours, in any of the languages of API Maker, which runs after an API, with its result in g.res.output. It can reshape the answer, add to it, replace it, send something somewhere, or refuse to answer at all. It lives at the same levels as a pre hook : instance, database, table, API, custom and system API, with optional groups.

Hooks around an API : pre hooks from the instance down to the API, the API, then post hooks from the API up to the instance request Caller with tokens pre hooks · top to bottom Instance every table of it Database every table of it Table every API of it This API get all only… The API database · cache post hooks · bottom to top This API g.res.output Table Database Instance Reply to the caller a pre hook which returns a value, or throws, answers here : nothing after it runs Also hooked Custom APIs System APIs A hook with groups runs only for API users of those groups Cached answers run no hook Calls from your own code (g.sys.db…) skip the hooks unless you pass skipHookRunning: false.

Order

Post hooks run from the narrowest level to the widest : the hooks of the API, then of the table, then of the database, then of the instance, each list top to bottom. The last one to run sees what every other one did.

In API Testing, the Post Hooks tab of an API of a table lists every post hook which runs after it, in that order : its own, then the hooks of its table, its database and its instance (marked Table, Database, Instance : they are changed in their categories of API Testing). In Git, every hook is a folder of its own.

A post hook is written in the language of its API, as every hook is : the code of an API and all its hooks are one language on one runtime.

The code

 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) {
    if (!g.req.isApiRequestFromUser) return;

    // g.res.output : the answer of the API (data), changeable
    // g.res.statusCode, g.res.warnings, g.res.errors
    // g.req : the request as the API saw it, after the pre hooks
    // g.res.shared : what the pre hooks left for you
}
module.exports = main;

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


async def main(g: G):
    if not g.req.is_api_request_from_user:
        return

    # g.res.output : the answer of the API (data), changeable
    # g.res.status_code, g.res.warnings, g.res.errors
    # g.req : the request as the API saw it, after the pre hooks
    # g.res.shared : what the pre hooks left for you

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?php
function main(AmG $g)
{
    if (!$g->req->isApiRequestFromUser) {
        return null;
    }

    // $g->res->output : the answer of the API (data), changeable
    // $g->res->statusCode, $g->res->warnings, $g->res->errors
    // $g->req : the request as the API saw it, after the pre hooks
    // $g->res->shared : what the pre hooks left for you
    return null;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        if (!g.Req.IsApiRequestFromUser) return null;

        // g.Res.Output : the answer of the API (data), changeable
        // g.Res.StatusCode, g.Res.Warnings, g.Res.Errors
        // g.Req : the request as the API saw it, after the pre hooks
        // g.Res.Shared : what the pre hooks left for you
        return null;
    }
}

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

import "apimaker/am"

func Main(g *am.G) (any, error) {
    if !g.Req.IsApiRequestFromUser() {
        return nil, nil
    }

    // g.Res.Output() : the answer of the API (data), changeable with g.Res.SetOutput
    // g.Res.StatusCode(), g.Res.Warnings(), g.Res.Errors()
    // g.Req : the request as the API saw it, after the pre hooks
    // g.Res.Shared() : what the pre hooks left for you
    return nil, nil
}

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

pub fn main(g: &mut G) -> Result<Value, Errors> {
    if !g.req.is_api_request_from_user() {
        return Ok(Value::Null);
    }

    // g.res.output_mut() : the answer of the API (data), changeable
    // g.res.status_code(), g.res.warnings(), g.res.errors()
    // g.req : the request as the API saw it, after the pre hooks
    // g.res.shared() : what the pre hooks left for you
    Ok(Value::Null)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import am.G;

class Api {
    static Object main(G g) {
        if (!g.req.isApiRequestFromUser()) return null;

        // g.res.getOutput() : the answer of the API (data), changeable with g.res.setOutput
        // g.res.getStatusCode(), g.res.getWarnings(), g.res.getErrors()
        // g.req : the request as the API saw it, after the pre hooks
        // g.res.getShared() : what the pre hooks left for you
        return null;
    }
}

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

fun main(g: G): Any? {
    if (!g.req.isApiRequestFromUser) return null

    // g.res.output : the answer of the API (data), changeable
    // g.res.statusCode, g.res.warnings, g.res.errors
    // g.req : the request as the API saw it, after the pre hooks
    // g.res.shared : what the pre hooks left for you
    return null
}
The hook Effect
returns nothing The next post hook runs, then the answer is sent.
changes g.res.output The answer is what is in g.res.output at the end.
returns a value That value becomes the answer and the remaining post hooks do not run.
throws The request answers with the error, whatever the API did. The database change of the API is not rolled back by that.
  • A hook in any language other than TypeScript runs in the sandbox of its language. A hook in TypeScript runs inside API Maker when it needs nothing of a sandbox, else in its sandbox of Node.js or Bun ; the answer is the same. (runOnNativeProcess runs a hook on the machine of the server.) Every hook runs within the sandbox timeout of the call.
  • No hook runs when the answer comes from the cache. Calls from your own code skip hooks unless skipHookRunning: false.

Reshape the answer

Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import * as T from 'types';

async function main(g: T.IAMGlobal) {
    if (!g.req.isApiRequestFromUser) return;
    const rows = Array.isArray(g.res.output) ? g.res.output : [ g.res.output ];
    for (const row of rows) {
        if (!row) continue;
        delete row.password;
        row.amount_with_tax = Math.round(row.amount * 1.18);
    }
}
module.exports = main;
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from am import G


async def main(g: G):
    if not g.req.is_api_request_from_user:
        return
    rows = g.res.output if isinstance(g.res.output, list) else [g.res.output]
    for row in rows:
        if not row:
            continue
        row.pop('password', None)
        row['amount_with_tax'] = round((row.get('amount') or 0) * 1.18)
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<?php
function main(AmG $g)
{
    if (!$g->req->isApiRequestFromUser) {
        return null;
    }
    $output = $g->res->output;
    $rows = is_array($output) && array_is_list($output) ? $output : [$output];
    foreach ($rows as $row) {
        if (!$row) {
            continue;
        }
        unset($row->password);
        $row->amount_with_tax = round(($row->amount ?? 0) * 1.18);
    }
    return null;
}
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        if (!g.Req.IsApiRequestFromUser) return null;
        IEnumerable<JsonObject> rows = g.Res.Output switch
        {
            JsonArray list => list.OfType<JsonObject>(),
            JsonObject row => [row],
            _ => [],
        };
        foreach (var row in rows)
        {
            row.Remove("password");
            row["amount_with_tax"] = Math.Round(row.GetDouble("amount") * 1.18);
        }
        return null;
    }
}
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
package code

import (
    "math"

    "apimaker/am"
)

func Main(g *am.G) (any, error) {
    if !g.Req.IsApiRequestFromUser() {
        return nil, nil
    }
    rows, isList := g.Res.Output().([]any)
    if !isList {
        rows = []any{g.Res.Output()}
    }
    for _, each := range rows {
        row := am.AsM(each)
        if row == nil {
            continue
        }
        delete(row, "password")
        row["amount_with_tax"] = math.Round(row.Float("amount") * 1.18)
    }
    return nil, nil
}
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
use am::{Errors, G, Value, json};

pub fn main(g: &mut G) -> Result<Value, Errors> {
    if !g.req.is_api_request_from_user() {
        return Ok(Value::Null);
    }
    let output = g.res.output_mut();
    let rows: Vec<&mut Value> = match output {
        Value::Array(rows) => rows.iter_mut().collect(),
        row => vec![row],
    };
    for row in rows {
        let Some(row) = row.as_object_mut() else { continue };
        row.remove("password");
        let amount = row.get("amount").and_then(Value::as_f64).unwrap_or(0.0);
        row.insert("amount_with_tax".to_owned(), json!((amount * 1.18).round()));
    }
    Ok(Value::Null)
}
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import am.G;
import java.util.List;
import java.util.Map;

class Api {
    static Object main(G g) {
        if (!g.req.isApiRequestFromUser()) return null;
        Object output = g.res.getOutput();
        List<?> rows = output instanceof List<?> list ? list : List.of(output);
        for (Object each : rows) {
            if (!(each instanceof Map<?, ?> row)) continue;
            @SuppressWarnings("unchecked")
            Map<String, Object> columns = (Map<String, Object>) row;
            columns.remove("password");
            Object amount = columns.get("amount");
            columns.put("amount_with_tax", Math.round((amount instanceof Number number ? number.doubleValue() : 0) * 1.18));
        }
        return null;
    }
}
Hide a field and add a computed one
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import am.G

fun main(g: G): Any? {
    if (!g.req.isApiRequestFromUser) return null
    val rows = g.res.output as? List<*> ?: listOf(g.res.output)
    for (each in rows) {
        @Suppress("UNCHECKED_CAST")
        val row = each as? MutableMap<String, Any?> ?: continue
        row.remove("password")
        row["amount_with_tax"] = Math.round(((row["amount"] as? Number)?.toDouble() ?: 0.0) * 1.18)
    }
    return null
}

Do something after a write

Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import * as T from 'types';

async function main(g: T.IAMGlobal) {
    if (!g.req.isApiRequestFromUser) return;
    const now = Date.now();   // milliseconds since 1970
    await g.sys.db.saveSingleOrMultiple({
        instance: 'mongodb', database: 'shop', collection: 'audit_logs',
        saveData: { api: g.req.reqInfo.apiInfo.id, by: g.req.auth.authAMDB?.email, at: now, took: now - g.res.shared.startedAt },
    });
    await g.sys.system.emitEvent('order-placed', g.res.output);
}
module.exports = main;
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import time

from am import G


async def main(g: G):
    if not g.req.is_api_request_from_user:
        return
    now = int(time.time() * 1000)  # milliseconds since 1970
    await g.sys.db.save_single_or_multiple(
        'mongodb', 'shop', 'audit_logs',
        save_data={
            'api': g.req.req_info.apiInfo.id,
            'by': (g.req.auth.authAMDB or {}).get('email'),
            'at': now,
            'took': now - g.res.shared.startedAt,
        },
    )
    await g.sys.system.emit_event('order-placed', g.res.output)
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<?php
function main(AmG $g)
{
    if (!$g->req->isApiRequestFromUser) {
        return null;
    }
    $now = (int) (microtime(true) * 1000); // milliseconds since 1970
    $g->sys->db->saveSingleOrMultiple('mongodb', 'shop', 'audit_logs', saveData: [
        'api' => $g->req->reqInfo->apiInfo->id,
        'by' => $g->req->auth->authAMDB?->email,
        'at' => $now,
        'took' => $now - $g->res->shared->startedAt,
    ]);
    $g->sys->system->emitEvent('order-placed', $g->res->output);
    return null;
}
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        if (!g.Req.IsApiRequestFromUser) return null;
        var now = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(); // milliseconds since 1970
        await g.Sys.Db.SaveSingleOrMultiple(new Save("mongodb", "shop", "audit_logs", new
        {
            api = g.Req.ReqInfo.GetObject("apiInfo").GetString("id"),
            by = g.Req.Auth.GetObject("authAMDB").GetString("email"),
            at = now,
            took = now - g.Res.Shared.GetInt64("startedAt"),
        }));
        await g.Sys.System.EmitEvent("order-placed", g.Res.Output?.DeepClone());
        return null;
    }
}
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
package code

import (
    "time"

    "apimaker/am"
)

func Main(g *am.G) (any, error) {
    if !g.Req.IsApiRequestFromUser() {
        return nil, nil
    }
    now := time.Now().UnixMilli() // milliseconds since 1970
    _, err := g.Sys.Db.SaveSingleOrMultiple(am.Save{
        Instance: "mongodb", Database: "shop", Collection: "audit_logs",
        SaveData: am.M{
            "api":  g.Req.ReqInfo().Map("apiInfo").String("id"),
            "by":   g.Req.Auth().Map("authAMDB").Get("email"),
            "at":   now,
            "took": now - g.Res.Shared().Int("startedAt"),
        },
    })
    if err != nil {
        return nil, err
    }
    _, err = g.Sys.System.EmitEvent("order-placed", g.Res.Output())
    return nil, err
}
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
use std::time::{SystemTime, UNIX_EPOCH};

use am::{Errors, G, Save, Value, json};

pub fn main(g: &mut G) -> Result<Value, Errors> {
    if !g.req.is_api_request_from_user() {
        return Ok(Value::Null);
    }
    let now = SystemTime::now().duration_since(UNIX_EPOCH).map_or(0, |since| since.as_millis() as i64); // milliseconds since 1970
    g.sys.db.save_single_or_multiple(Save::new(
        "mongodb",
        "shop",
        "audit_logs",
        json!({
            "api": g.req.req_info()["apiInfo"]["id"],
            "by": g.req.auth()["authAMDB"]["email"],
            "at": now,
            "took": now - g.res.shared()["startedAt"].as_i64().unwrap_or(now),
        }),
    ))?;
    g.sys.system.emit_event("order-placed", g.res.output().clone(), &[])?;
    Ok(Value::Null)
}
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import am.G;
import am.JsonObject;
import am.Save;

class Api {
    static Object main(G g) {
        if (!g.req.isApiRequestFromUser()) return null;
        long now = System.currentTimeMillis(); // milliseconds since 1970
        g.sys.db.saveSingleOrMultiple(new Save("mongodb", "shop", "audit_logs", JsonObject.of(
            "api", g.req.getReqInfo().getObject("apiInfo").getString("id"),
            "by", g.req.getAuth().getObject("authAMDB").get("email"),
            "at", now,
            "took", now - g.res.getShared().getLong("startedAt"))));
        g.sys.system.emitEvent("order-placed", g.res.getOutput());
        return null;
    }
}
Audit row and an event after a save
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import am.G
import am.Save

fun main(g: G): Any? {
    if (!g.req.isApiRequestFromUser) return null
    val now = System.currentTimeMillis() // milliseconds since 1970
    g.sys.db.saveSingleOrMultiple(
        Save(
            "mongodb", "shop", "audit_logs",
            mapOf(
                "api" to g.req.reqInfo.getObject("apiInfo").getString("id"),
                "by" to g.req.auth.getObject("authAMDB")["email"],
                "at" to now,
                "took" to now - g.res.shared.getLong("startedAt"),
            ),
        ),
    )
    g.sys.system.emitEvent("order-placed", g.res.output)
    return null
}
  • For a notification to WebSocket clients, nothing to write : subscribers of the table are notified after every successful call. Emit a custom WebSocket event with g.sys.system.emitEventWS when the notification needs another shape.
  • For an event after an API hit without code, attach the event to the API on the Events page (automatic trigger).

Streams

On get all by stream and query by stream the rows are already on their way when the post hooks run : g.res.output only holds the last chunk, and a value returned or thrown can not change what was sent. Reshape a stream in a custom API around g.sys.db.getAllByStream instead.

Good to know

  • WebSocket notifications and automatic events run after the post hooks, on the final answer. A post hook which throws still lets the notification go out ; a pre hook which throws does not.
  • Post hooks have versions and a Test button on the API testing page, like pre hooks, and deploy with Git.
← Pre hooks Events