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

All APIs at a glance

Everything API Maker serves sits behind one base URL and the same token header. This page is the map ; every operation has its own page with examples.

The API families : one base URL, one token, five HTTP families 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 TypeScript function, any path and method System APIs /api/system-api/… 24 ready APIs : tokens, encrypt, cache, events, indexes, checks Third party APIs /api/third-party/… bundles installed from the store deprecated, goes in v4 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

The URL of a table

Anatomy of a database API URL : /api/schema/admin/mysql8/inventory/customers/get-by-id/42 /api /schema /admin /mysql8 /inventory /customers /get-by-id/42 prefix always family schema or gen user path of the account (admin, dev1…) instance a database server crm::acme for a tenant database table / collection operation and its params nothing = get all · get-by-id/:id/:primaryKey query · count · distinct/:field · save-single-or-multiple … Query params follow the URL : ?find={…}&select=…&limit=10&deep=[…]
Segment Meaning
/api/schema or /api/gen The family : schema APIs apply the schema of the table, generated APIs are schemaless.
user-path The API path of the admin or developer account which owns the instance (admin for the first admin). It is shown on the profile of the account.
instance The name of the instance (the database server) in API Maker. For a tenant of a multi-tenant instance : instance::tenant.
database The database on that server.
table The table or collection.

Generated (/api/gen) or schema (/api/schema) ?

Both families offer the same operations on the same URL pattern. The schema APIs read the schema of the table : values are converted to their types, validated, encrypted, defaulted and numbered before they reach the database. The generated APIs are schemaless : they pass your data as it is, so a number sent as "22" stays a string. Use the schema APIs for the tables your application writes to, and the generated APIs for quick reads and for tables without a schema.

Instances, databases and tables

API Info → DB API has four panels, left to right : instances, databases, tables, APIs. Pick one in each and the next panel fills.

Panel What it holds
Instances A connection to a database server : MongoDB, MySQL (TiDB, Percona), MariaDB, SQL Server, PostgreSQL, Oracle. Add New takes the database type, a unique Instance Name (used in every URL and in code, it can not change later), the Connection String picked among the keys of the secret and Max Pool Connections ; Oracle adds the username, the password and the privilege. Saving tests the connection first : an instance which can not connect is not saved.
Databases The databases the connection sees, with their settings. Bulk Schema Creation generates the schema of every table at once ; Compact Database reclaims space on MongoDB.
Tables The tables or collections, with their schema, their indexes and their settings. Structure changed appears when the columns of a table differ from its schema : click to compare and update.
APIs The operations below, each with its settings and Test API, which opens the API testing page on it.
  • Connection String Sandbox : another string for the code which runs in the sandbox, when the sandbox reaches the database through another address. Empty, the main one is used.
  • Is Multi Tenant Structure Instance and Connection String Multi Tenant make a multi-tenant instance ; Select tenant then loads the databases of one tenant.

The 17 operations of a table

The paths below follow /api/schema/<user-path>/<instance>/<database>/<table> (and the same under /api/gen). [/:primaryKey] names another column to use as the key.

Operation Method and path Body Page (schema · gen)
Get all GET / query params schema · gen
Get all by stream GET /stream query params schema · gen
Get by id GET /get-by-id/:id[/:primaryKey] schema · gen
Save single or multiple POST /save-single-or-multiple one object or an array schema · gen
Master save POST /master-save objects with nested related objects schema · gen
Update by id PUT /update-by-id/:id[/:primaryKey] the fields to change schema · gen
Update many PUT /update-many { find, updateData } schema · gen
Replace by id MongoDB PUT /replace-by-id/:id[/:primaryKey] the whole document schema · gen
Array operations MongoDB PUT /array-operations { find, operations } schema · gen
Remove by id DELETE /:id[/:primaryKey] schema · gen
Remove by query POST /query/delete { find } schema · gen
Query for get data POST /query { find, select, sort, skip, limit, deep, getTotalCount } schema · gen
Query for get data by stream POST /query-stream same as query schema · gen
Aggregate MongoDB POST /aggregate a pipeline array schema · gen
Count POST /count { find } schema · gen
Distinct GET /distinct/:field[/:order] schema · gen
Distinct with query POST /distinct/:field[/:order] { find } schema · gen
  • MongoDB gets all 17. MySQL, MariaDB, SQL Server, PostgreSQL, Oracle, TiDB and Percona get 14 : replace by id, array operations and aggregate are MongoDB only.
  • The schema operations exist for a table only once it has an active schema. The generated ones are always there.
  • Their id in settings, groups, hooks and WebSocket subscriptions is SCHEMA_GET_ALL, GEN_POST_BULK_INSERT… : the full list is under API ids.

Shared by every read
Query params find, skip, limit, sort, select, deep, getTotalCount, and any column name as a filter. In the body for the query APIs.
Request headers Tokens, x-am-response-case, x-am-content-type-response, x-am-response-object-type, x-am-cache-control, x-am-get-encrypted-data, x-am-internationalization, x-am-tenant-username…
Response format { success, statusCode, data, totalCount, errors, warnings, logs, meta }

Your own APIs

Family Method and path Page
Custom API ANY /api/custom-api/<user-path>/<path> : the method and path of its settings Custom APIs
Pre and post hooks run around every API of the account Pre hook · Post hook
Events emitted by an API hit or by code, with listeners Events
WebSocket events pushed to subscribed clients WebSocket events
Schedulers intervals and cron Schedulers
Utility classes shared code, import * as x from 'utils/X' Utility classes

System APIs

All under /api/system-api/<user-path>/…, all POST, and all available in code as g.sys.system.* or g.sys.cache.*.

Group APIs
Security /token · /encrypt-data · /decrypt-data · /hash-data · /get-secret-by-name
Redis and cache /get-redis-key · /set-redis-key · /remove-redis-key · /reset-redis-cache-db · /reset-redis-cache-custom-apis · /reset-redis-cache-system-apis · /reset-redis-cache-third-party-apis
Databases /get-table-meta · /create-indexes · /drop-indexes · /get-indexes · /multi-tenant-instance-updated · executeQuery from code
Events /emit-event · /emit-event-ws
Validation /is-valid-data-for-table · /is-valid-data-for-custom-api · /is-valid-data-for-third-party-api
Outside /call-external-api

From your code

Every API above is a method of the global object g : g.sys.db.getAll, g.sys.db.gen.queryGen, g.sys.system.encrypt, g.sys.cache.setKey… with the same headers and query params, and an example for each one.

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

async function main(g: T.IAMGlobal) {
    const products = await g.sys.db.getAll<db.mongodb.shop.IProducts>({
        instance: 'mongodb', database: 'shop', collection: 'products',
        queryParams: { find: { status: 'ACTIVE' }, limit: 10, deep: [{ s_key: 'category' }] },
    });
    return products;
}
module.exports = main;

API ids

The ids used in groups, settings, hooks, events and WebSocket subscriptions.

Schema APIs

  • SCHEMA_GET_ALL
  • SCHEMA_GET_ALL_STREAM
  • SCHEMA_GET_BY_ID
  • SCHEMA_POST_BULK_INSERT
  • SCHEMA_MASTER_SAVE
  • SCHEMA_ARRAY_OPERATIONS
  • SCHEMA_UPDATE_MANY
  • SCHEMA_PUT_UPDATE_BY_ID
  • SCHEMA_PUT_REPLACE_BY_ID
  • SCHEMA_DEL_DELETE_BY_ID
  • SCHEMA_POST_QUERY
  • SCHEMA_POST_QUERY_STREAM
  • SCHEMA_POST_QUERY_DELETE
  • SCHEMA_POST_AGGREGATE
  • SCHEMA_POST_COUNT
  • SCHEMA_GET_DISTINCT
  • SCHEMA_POST_DISTINCT_QUERY

Generated APIs

  • GEN_GET_ALL
  • GEN_GET_ALL_STREAM
  • GEN_GET_BY_ID
  • GEN_POST_BULK_INSERT
  • GEN_MASTER_SAVE
  • GEN_ARRAY_OPERATIONS
  • GEN_UPDATE_MANY
  • GEN_PUT_UPDATE_BY_ID
  • GEN_PUT_REPLACE_BY_ID
  • GEN_DEL_DELETE_BY_ID
  • GEN_POST_QUERY
  • GEN_POST_QUERY_STREAM
  • GEN_POST_QUERY_DELETE
  • GEN_POST_AGGREGATE
  • GEN_POST_COUNT
  • GEN_GET_DISTINCT
  • GEN_POST_DISTINCT_QUERY

System APIs

  • EXECUTE_PLAIN_QUERY
  • ENCRYPT_DATA
  • DECRYPT_DATA
  • HASH_DATA
  • GET_TOKEN
  • CALL_EXTERNAL_API
  • GET_SECRET
  • GET_REDIS_KEY
  • SET_REDIS_KEY
  • REMOVE_REDIS_KEY
  • CUSTOM_USER_CACHING
  • RESET_REDIS_CACHE_DB
  • RESET_REDIS_CACHE_CUSTOM_APIS
  • RESET_REDIS_CACHE_SYSTEM_APIS
  • RESET_REDIS_CACHE_TP_APIS
  • GET_TABLE_META
  • EMIT_EVENT
  • EMIT_EVENT_WS
  • IS_VALID_DATA_FOR_TABLE
  • IS_VALID_DATA_FOR_CUSTOM_API
  • IS_VALID_DATA_FOR_THIRD_PARTY_API