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

How API Maker works

API Maker is a server you install, not a library you embed. Your apps call it over HTTP, it talks to your databases, and your own code, in TypeScript, Python, PHP, C#, Go, Rust, Java or Kotlin, runs beside it in sandboxes. This page shows the pieces once, so every other page makes sense.

The life of a request

The life of a request : app → Caddy → token and groups → pre hooks → the API → post hooks → reply Your app web · mobile · server or an AI agent Caddy HTTPS ends here :443 → :38246 API Maker one process, or a cluster behind Caddy Token & groups API gate · row gate 401 · 403 if not Pre hooks your code check · change · stop The API schema · generated custom · system Post hooks your code reshape · notify Reply JSON · XML YAML · text · file Redis cache answers again in µs Your databases MongoDB · SQL · Oracle The API asks the cache first when caching is on, then the database. Sandboxed : your code runs in Docker containers, apart from API Maker. x-am-authorization 200 · 201 with data, or 400 · 401 · 403 · 404 with every error at once
  1. Your app calls a URL such as GET /api/schema/admin/shop/main/customers?limit=10 with the token of its API user in x-am-authorization.
  2. Caddy (installed by the install script) ends HTTPS and forwards to API Maker on port 38246 : the APIs and the WebSockets share that port.
  3. Token and groups : API Maker checks the token, finds the API user and its groups, and refuses the call with 401 (no valid token) or 403 (no group grants this API of this table). When the table asks for a person token too, that token is checked the same way.
  4. Pre hooks you wrote for the instance, the database, the table or this API run in order. They can change the request, add a filter such as "only the rows of this person", answer directly, or throw.
  5. The API runs : a generated or schema API talks to the database, a custom API runs your function in the sandbox, a system API does its job. With caching on, the answer comes from Redis when it is there.
  6. Post hooks run with the result and can reshape it, notify, or throw.
  7. The reply goes back in the envelope { success, statusCode, data | errors }, as JSON, XML, YAML or text, with the key case you asked for in the headers. WebSocket subscribers of that API or table get their notification.

Every step is logged when a log profile selects the API, and counted in the analytics dashboard.

One base URL, several families

The API families : one base URL, one token, four HTTP families, your code in any language and the code API Maker runs for you https://api.example.com/api/… one host, one token header, every family below Schema APIs /api/schema/… 17 per table · types, rules, encryption, ids from the schema Generated APIs /api/gen/… 17 per table · schemaless, data passes as it is Custom APIs /api/custom-api/… your function, in any language, any path and method System APIs /api/system-api/… 23 ready APIs : tokens, encrypt, cache, events, indexes, checks Your code TypeScript on Node.js or Bun Python · PHP · C# · Go · Rust Java · Kotlin one g in every language Run by API Maker, not called over HTTP Events after an API hit or from your code · Schedulers on intervals and cron · WebSocket events pushed to clients Process initializers when a sandbox starts · Migration scripts on deploy · Hooks around every API · Test cases
Family URL What it is Where it is described
Schema APIs /api/schema/<user-path>/<instance>/<database>/<table>/… The operations of a table (17 on MongoDB, 14 on SQL tables), which apply the schema of the table All APIs
Generated APIs /api/gen/<user-path>/<instance>/<database>/<table>/… The same operations, without a schema All APIs
Custom APIs /api/custom-api/<user-path>/<your path> Your function, in any language, behind the path and method you choose Custom APIs
System APIs /api/system-api/<user-path>/<name> Ready made APIs : tokens, encryption, hashing, secrets, Redis keys, cache resets, events, indexes, validations System APIs
Not over HTTP Events, schedulers, WebSocket events, process initializers, migration scripts, hooks and test cases : code API Maker runs for you

<user-path> is the API path of the admin or developer account which owns the item : admin for the first admin account. Each developer account has its own path, its own instances, secrets and code, on the same server.

The two tokens and the two gates

Two tokens, two gates : the API user (which application) and the person (which rows) 1 · get the tokens The application POST …/system-api/admin/token { "u": "shop_app", "p": "…" } an API user of API Maker → x-am-authorization The person POST …/system-api/admin/token { "name": "users_tg", "u": "alice", "p": "…" } a row of your users table → x-am-user-authorization Google, Azure AD, AWS Cognito and custom providers give the person token too : x-google-authorization… 2 · call an API with both GET /api/schema/admin/shop/main/orders x-am-authorization: eyJ… x-am-user-authorization: eyJ… Public APIs (IS_PUBLIC) need no token. Token access needs the API user, and the person only when the settings name an auth provider. 401 · token missing or expired 403 · no group grants the API 3 · two gates in API Maker API gate the groups of the API user may this application call this API of this table ? which fields it may read and write 403 when no group grants it Row gate your pre hook of the rows this API reaches, which are this person's ? g.req.auth.authAMDB find = { owner: person.id } only the rows of Alice, only the fields her app may see
  • The API user is an application : your web app, your mobile app, a partner. It is created on the API user permissions page, gets a token from the token API with its username and password, and sends it in x-am-authorization. Its groups are the API gate : which APIs, tables and fields it may read and write.
  • The person is a row of your own users table, or a Google, Azure AD, AWS Cognito or custom identity. An auth provider turns it into a token sent in x-am-user-authorization (or the header of the provider). Your code reads it in g.req.auth, and a pre hook is the row gate : it narrows every request to the rows of that person.
  • A new account starts with an API user named default (password 12345, kept in the default secret under common.apiUserPasswords.default) and a group Default which allows everything. Replace both before you go live : one small group per screen is the pattern described in Handle role based permissions.
  • Public APIs (apiAccessType: IS_PUBLIC in the settings) skip both tokens.

Where your code runs

  • The sandbox. Your code runs in Docker containers of its account, apart from the API Maker process. Each call gets a time to run : the one its item names (seconds for a custom API, minutes for a scheduler, an event listener, a migration script or a process initializer), else 13000 ms. The header x-am-sandbox-timeout changes it per call (time of a run). Custom APIs, hooks, event listeners, schedulers, migration scripts, process initializers, utility classes and test cases are written in any of the languages : TypeScript on Node.js or Bun, Python, PHP, C#, Go, Rust, Java or Kotlin. Each language has its own sandboxes, built from the runtime, version, packages and Dockerfile of the sandbox settings : nothing is installed that the account did not add.
  • The native process. A custom API with runOnNativeProcess: true runs on the machine of the server instead of in Docker, in one runner per runtime shared by every account (the runtime must be installed there : node, python3…), for the few cases that need it : a browser with Playwright, or the lowest possible latency. It is faster and less isolated. Like a sandbox, that runner answers what the code asks of g.sys itself (the databases, Redis) and hands only the answer back to the server.
  • Settings run in the server. Code which only describes (the Basic Info of a custom API, the settings of APIs, schemas, the texts of internationalization, secrets) is TypeScript which API Maker runs itself, the moment you save it : what it exports is JSON for the database, so it needs no sandbox. It imports types and your utility classes written in TypeScript, no packages : where settings run.
  • The global object g. Your code gets one object with the request (g.req), the response (g.res), every API of API Maker (g.sys.db, g.sys.system, g.sys.cache), a logger and a shared space, in every language : Global object g.
  • Code in the browser. You write the code in the admin panel : TypeScript with the types of API Maker (import * as T from 'types') and the interfaces generated from your schemas (import * as db from 'db-interfaces'), or another language picked above the editor. Saving builds the code of compiled languages at once, and what does not compile is told in the console of the account. Or in your own editor, with the local client syncing the files both ways.

The servers

One server after the install script : Caddy → systemd (API Maker : APIs, WebSockets, admin panel) → Docker (MongoDB, Redis, sandboxes) → your databases Internet apps · users Your Ubuntu server 1 vCPU · 1 GB RAM is enough to start Caddy :80 · :443 (SSL) reverse proxy automatic HTTPS systemd · one program API Maker :38246 APIs · WebSockets every core of the server api_maker_be.service Admin panel :4626 · served by API Maker Docker MongoDB API Maker's own data · :38248 Redis cache · counters · :7479 Sandboxes your custom code runs here one per account and language Files /root/config/.env · /root/config/Caddyfile /root/projects/api_maker · /root/logs · /root/docker-data Your databases MongoDB · MySQL · MariaDB PostgreSQL · SQL Server Oracle · TiDB · Percona on this server, or anywhere reached through the connection strings of your secret
  • API Maker is one process per server, run by systemd : systemd starts it when the server boots and again if it stops. Its threads use every core (one process, every core). Several servers behind Caddy form a cluster : schedulers are spread over the servers and run once per tick, a saved change and WebSocket notifications reach every server through Redis.
  • MongoDB (a replica set) holds the data of API Maker itself : accounts, schemas, code, settings, logs. Your data stays in your databases.
  • Redis holds the cache, the auto increment counters and what the servers of a cluster share.
  • The admin panel is a static site that API Maker serves itself on a port of its own (4626, the adminPanel settings) : Caddy puts it on port 80 or on the domain you gave it. It talks to the same API, through an encrypted channel of its own. That channel keeps what the panel sends from whoever only listens on the way ; it does not prove to the browser that it is your server which answers. Only HTTPS does : give the install script a domain (Caddy then serves the panel and the API over HTTPS), or put a proxy with a certificate in front, before people rely on the installation.
  • Sandboxes : your code runs in Docker containers called sandboxes, one per language of an account. When one is busy, API Maker starts another, up to the sandbox count.
  • Your databases can be on the same server or anywhere the server can reach. The connection strings live in the default secret.

The install page shows what the install script sets up ; the deployment architectures on the website go from one server to a global fleet.

What happens on a save

The stages of a write through a schema API, in order, from the request to 201 or 400 POST body "price": "25" "name": " Mouse " Keys not in the schema : 400 Types "25" → 25 date, objectId Clean trim, case defaults conversionFun your function, its return is kept Secure encrypt · hash with your secret Ids ObjectID, UUID auto increment Rules required, min, length, email, enum validatorFun your rule, with the whole object 201 · saved, row returned ids and defaults filled in 400 · every error at once nothing is saved Generated APIs (/api/gen) skip all of this.

A write through a schema API is converted and checked before it reaches the database : keys not in the schema are refused, values get their types, strings are trimmed and cased, your conversionFun runs, fields are encrypted or hashed, ids and defaults are filled in, then the rules and your validatorFun decide. Everything wrong is answered at once, with 400 and one entry per problem, and nothing is saved. Table schema describes every option.

Everything is in Git

Schemas, settings, custom APIs, hooks, events, schedulers, utility classes, migrations, test cases and the security report are files in a Git repository. The admin panel commits and pushes them ; a Git pull on another server is the deployment. Secrets never go to Git. See Git integration and Deploy API Maker for the upgrade of API Maker itself.

Next : your first API → All APIs at a glance Install on a server