# How API Maker Works > The moving parts of API Maker in one page - the life of a request, the API families on one base URL, the two tokens and the two gates, where your TypeScript code runs, and what the servers look like. Source: https://docs.apimaker.dev/v1/docs/getting-started/how-it-works.html 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 TypeScript runs inside it in a sandbox. This page shows the pieces once, so every other page makes sense. ## The life of a request > Diagram : The life of a request : app → Caddy → token and groups → pre hooks → the API → post hooks → reply > > The life of a request in API Maker : the app calls through Caddy, API Maker checks the token and the groups, runs the pre hooks, the API itself against the database or the cache, the post hooks, and replies in JSON, XML or YAML. 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`. WebSockets go to `38245`. 3. **Token and groups** : API Maker checks the token, finds the API user and its [groups](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html), 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](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) `{ success, statusCode, data | errors }`, as JSON, XML, YAML or text, with the key case you asked for in the [headers](https://docs.apimaker.dev/v1/docs/apis-all/header/requestHeader.html). WebSocket subscribers of that API or table get their notification. Every step is logged when a [log profile](https://docs.apimaker.dev/v1/docs/logs/log-profile.html) selects the API, and counted in the analytics dashboard. ## One base URL, several families > Diagram : The API families : one base URL, one token, five HTTP families and the code API Maker runs for you > > The API families of API Maker on one base URL : schema APIs under /api/schema, generated APIs under /api/gen, custom APIs under /api/custom-api, system APIs under /api/system-api, third party APIs under /api/third-party, and the code API Maker runs on its own : events, schedulers, WebSocket events, process initializers and migrations. | Family | URL | What it is | Where it is described | |---|---|---|---| | Schema APIs | `/api/schema/////…` | 17 operations per table which apply the [schema](https://docs.apimaker.dev/v1/docs/schema/schema.html) of the table | [All APIs](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) | | Generated APIs | `/api/gen////
/…` | The same 17 operations, schemaless | [All APIs](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) | | Custom APIs | `/api/custom-api//` | Your TypeScript function behind the path and method you choose | [Custom APIs](https://docs.apimaker.dev/v1/docs/apis-all/custom-apis/user-created-custom-api.html) | | System APIs | `/api/system-api//` | Ready made APIs : tokens, encryption, hashing, secrets, Redis keys, cache resets, events, indexes, validations | [System APIs](https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-token-api.html) | | Third party APIs | `/api/third-party////` | Bundles installed from the API Maker store (deprecated, removed in v4) | [Third party APIs](https://docs.apimaker.dev/v1/docs/apis-all/thirdParty-apis/installed-third-party-api.html) | | Not over HTTP | | [Events](https://docs.apimaker.dev/v1/docs/apis-all/events/user-created-events-api.html), [schedulers](https://docs.apimaker.dev/v1/docs/apis-all/schedulers/user-created-schedulers-api.html), [WebSocket events](https://docs.apimaker.dev/v1/docs/pages/web-socket-event-page.html), [process initializers](https://docs.apimaker.dev/v1/docs/features/process-initializers.html), [migration scripts](https://docs.apimaker.dev/v1/docs/features/database-migration.html), [hooks](https://docs.apimaker.dev/v1/docs/apis-all/hooks/preHook-api.html) and [test cases](https://docs.apimaker.dev/v1/docs/test-cases/test-cases.html) : code API Maker runs for you | | `` is the API path of the admin or developer account which owns the item : `admin` for the first admin account. Each [developer account](https://docs.apimaker.dev/v1/docs/dev-accounts/dev-accounts.html) has its own path, its own instances, secrets and code, on the same server. ## The two tokens and the two gates > Diagram : Two tokens, two gates : the API user (which application) and the person (which rows) > > Two identities on every request : the API user token from the token API in x-am-authorization tells which application calls, and the token of a person from a token generator in x-am-user-authorization tells who the person is. Groups of the API user decide which APIs, tables and fields may be called ; pre hooks decide which rows belong to the person. - The **API user** is an application : your web app, your mobile app, a partner. It is created on the [API user permissions](https://docs.apimaker.dev/v1/docs/apis-security/api-user-permission.html) page, gets a token from the [token API](https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-token-api.html) with its username and password, and sends it in `x-am-authorization`. Its [groups](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html) 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](https://docs.apimaker.dev/v1/docs/authorization/AMDB.html) 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](https://docs.apimaker.dev/v1/docs/authorization/handle-role-based-permissions.html). - Public APIs (`apiAccessType: IS_PUBLIC` in the [settings](https://docs.apimaker.dev/v1/docs/settings/apiSettings.html)) skip both tokens. ## Where your code runs - **The sandbox.** Custom APIs, hooks, events, schedulers, migrations, utility classes and test cases run in Docker containers apart from the API Maker process, with a time limit (`13000` ms by default, the header `x-am-sandbox-timeout` changes it per call) and their own npm packages, installed from the [sandbox settings](https://docs.apimaker.dev/v1/docs/settings/sandboxSettings.html). Every admin account gets its own sandbox containers. - **The native process.** A custom API with `runOnNativeProcess: true` runs inside API Maker itself, for the few cases that need it : native modules, a browser with [Playwright](https://docs.apimaker.dev/v1/docs/guides/browser-automation.html), or the lowest possible latency. It is faster and less isolated. - **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 : [Global object g](https://docs.apimaker.dev/v1/docs/pre-defined-terms/global-object-g.html). - **TypeScript in the browser.** You write the code in the admin panel, 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 in your own editor, with the [local client](https://docs.apimaker.dev/v1/docs/features/developer-tools.html#your-own-editor) syncing the files both ways. ## The servers > Diagram : One server after the install script : Caddy → systemd (API Maker backend, WebSocket) and the files of the admin panel → Docker (MongoDB, Redis, sandboxes) → your databases > > What the installer sets up on one Ubuntu server : Caddy on ports 80 and 443 in front, API Maker run by systemd as the service api_maker_be, its admin panel served by Caddy from its files, MongoDB and Redis in Docker for the internal data of API Maker, sandbox containers for your code, and your own databases anywhere. - **API Maker** is a Node.js 22 process run by systemd, as the service `api_maker_be` : systemd starts it when the server boots and again if it stops. `cpuCount` in its [configuration](https://docs.apimaker.dev/v1/docs/am-resources/api-maker-configurations.html) starts one worker per CPU core. Several servers behind Caddy form a cluster : schedulers run once per cluster, 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 : Caddy serves its files, on port `80` or on the domain you gave it (port `4626` on a server without Caddy, and on your computer with API Maker Local Run). It talks to the same API. - **Sandboxes** are Docker containers on the same server. - **Your databases** can be on the same server or anywhere the server can reach. The [connection strings](https://docs.apimaker.dev/v1/docs/Database-connection-string/mongodb-connection-strings.html) live in the default [secret](https://docs.apimaker.dev/v1/docs/secrets/secrets.html). The [install page](https://docs.apimaker.dev/v1/docs/getting-started/install-on-server.html) shows what the install script sets up ; the [deployment architectures](https://apimaker.dev/architectures) on the website go from one server to a global fleet. ## What happens on a save > Diagram : The stages of a write through a schema API, in order, from the request to 201 or 400 > > What a schema API does to every write : refuses unknown keys, converts the types, trims and cases strings, runs your conversion function, encrypts or hashes, fills ids and defaults, runs the rules and your validator function, then saves and answers 201, or answers 400 with every error at once and saves nothing. 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](https://docs.apimaker.dev/v1/docs/schema/schema.html) 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 and notes never go to Git. See [Git integration](https://docs.apimaker.dev/v1/docs/Git/git.html) and [Deploy API Maker](https://docs.apimaker.dev/v1/docs/features/deploy-api-maker.html) for the upgrade of API Maker itself. - [Next : your first API →](https://docs.apimaker.dev/v1/docs/getting-started/first-api.html) - [All APIs at a glance](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) - [Install on a server](https://docs.apimaker.dev/v1/docs/getting-started/install-on-server.html)