# Post Hooks

> Run your code (TypeScript, Python, PHP, C#, Go, Rust, Java or Kotlin) after any API of API Maker - reshape the answer in g.res.output, notify, log, or replace it - at the level of an instance, a database, a table, one API or a custom or system API, in the reverse order of the pre hooks.

Source: https://docs.apimaker.dev/v4/docs/apis-all/hooks/postHook-api.html

A post hook is a function of yours, in any of the [languages](https://docs.apimaker.dev/v4/docs/languages/index.html) 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](https://docs.apimaker.dev/v4/docs/apis-all/hooks/preHook-api.html) : instance, database, table, API, custom and system API, with optional groups.

> Diagram : 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
>
> Order of the hooks around a database API : the pre hooks of the instance, then of the database, then of the table, then of the API run before it ; the API runs ; the post hooks run in the opposite order, API, table, database, instance. A pre hook which returns a value answers the caller and stops everything after it.

## 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](https://docs.apimaker.dev/v4/docs/Git/git.html#hooks).

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](https://docs.apimaker.dev/v4/docs/languages/index.html#one-language).

## The code

**TypeScript**

```typescript
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;
```

**Python**

```python
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
```

**PHP**

```php
<?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;
}
```

**C#**

```csharp
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;
    }
}
```

**Go**

```go
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
}
```

**Rust**

```rust
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)
}
```

**Java**

```java
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;
    }
}
```

**Kotlin**

```kotlin
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](https://docs.apimaker.dev/v4/docs/languages/index.html#in-the-server) 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](https://docs.apimaker.dev/v4/docs/features/automatic-caching.html). Calls from your own code skip hooks unless `skipHookRunning: false`.

## Reshape the answer

**TypeScript**

**Hide a field and add a computed one**

```typescript
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;
```

**Python**

**Hide a field and add a computed one**

```python
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)
```

**PHP**

**Hide a field and add a computed one**

```php
<?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;
}
```

**C#**

**Hide a field and add a computed one**

```csharp
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;
    }
}
```

**Go**

**Hide a field and add a computed one**

```go
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
}
```

**Rust**

**Hide a field and add a computed one**

```rust
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)
}
```

**Java**

**Hide a field and add a computed one**

```java
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;
    }
}
```

**Kotlin**

**Hide a field and add a computed one**

```kotlin
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

**TypeScript**

**Audit row and an event after a save**

```typescript
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;
```

**Python**

**Audit row and an event after a save**

```python
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)
```

**PHP**

**Audit row and an event after a save**

```php
<?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;
}
```

**C#**

**Audit row and an event after a save**

```csharp
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;
    }
}
```

**Go**

**Audit row and an event after a save**

```go
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
}
```

**Rust**

**Audit row and an event after a save**

```rust
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)
}
```

**Java**

**Audit row and an event after a save**

```java
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;
    }
}
```

**Kotlin**

**Audit row and an event after a save**

```kotlin
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](https://docs.apimaker.dev/v4/docs/apis-all/events/user-created-events-api.html) 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](https://docs.apimaker.dev/v4/docs/apis-all/hooks/preHook-api.html)
- [Events](https://docs.apimaker.dev/v4/docs/apis-all/events/user-created-events-api.html)