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

Custom API settings

The Basic Info tab of a custom API is a TypeScript object : where the API answers, who may call it, and how it behaves. It is always TypeScript, whatever language the code of the API is written in, and API Maker runs it itself when you save : the tab shows TypeScript with a lock.
Page APIs & Logic → Custom API → the API → Basic Info.
Type T.ICustomApiSettingsTypes
URL /api/custom-api/<user path><path> with requestMethod. Path and method together are unique.
Basic Info
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import * as T from 'types';
import { EType } from 'types';

let customApi: T.ICustomApiSettingsTypes = {
    name: 'Create Customer',                 // unique ; the folder in Git
    requestMethod: T.ERequestMethod.POST,
    path: '/customers',
    enableCaching: false,
    resetCacheOnModificationOf: [
        // 'DB:mongodb:shop:customers',        // a write to this table resets the cache of this API
        // 'CA:other_custom_api',              // a call of that custom API resets it
    ],
    acceptOnlyEncryptedData: false,
    // customApiTimeoutInSeconds: 10,
    errorList: [ 'Unable to process this request' ],   // translatable in i18n
    apiAccessType: T.EAPIAccessType.TOKEN_ACCESS,
    // authProviders: ['users_tg'],
    reqBodySchema: {
        first_name: { __type: EType.string, validations: { required: true } },
        phone: { __type: EType.number, validations: { min: 5 } },
    },
    fileUpload: { enable: false, allowFileUploadFields: [ T.EFilesVariables.files ], validations: {} },
};
module.exports = customApi;

The keys

Key Meaning
name Unique name, also the folder of the API in Git.
path, requestMethod Where it answers : GET, POST, PUT or DELETE. /customers/:id gives g.req.params.id.
apiAccessType TOKEN_ACCESS (default), IS_PUBLIC, or NO_ACCESS for an API only your code calls.
authProviders The person tokens the call must carry. Absent : common.authProviders of the secret ; [] : the API user token alone.
enableCaching Cache the answer in Redis per body, query and person.
resetCacheOnModificationOf DB:instance:database:table, CA:custom API name : what drops the cached answers. Otherwise reset custom API cache.
acceptOnlyEncryptedData Refuse plain payloads : encrypted payloads.
reqBodySchema, reqQueryParametersSchema A schema for the body and the query : validated and converted before the code runs, checkable with is valid data for custom API.
customApiTimeoutInSeconds How long the code of the API and the hooks of its versions may run, in seconds, in the sandbox and with runOnNativeProcess alike. Empty : sandboxReqTimeout (13 seconds). A request which sends x-am-sandbox-timeout is given that time instead : time of a run.
runOnNativeProcess Run on the process of API Maker instead of the sandbox : faster, less isolated ; console.log is not captured, use g.logger.
errorList The messages this API throws, listed for internationalization.
fileUpload enable, allowFileUploadFields (files…), and per field validations : minFileSizeBytes, maxFileSizeBytes, allowedExtensionsArr. See files.
swaggerDocs tag, summary, description, parameters for the Swagger docs of the API users.
separateSandboxSettings Sandboxes of their own for this API : see below.

The language of the code of the API is chosen in the title bar of its editor, not here : see languages.

Separate sandbox

By default the code of a custom API runs in the sandboxes of its language, with the packages of the Sandbox Settings. An API which needs other packages, another runtime or version, or which must not share its sandboxes with the rest, names a group : every API of the account which names the same group shares its sandboxes, and no other code runs there.

Reports in a sandbox of their own, on Bun
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
let customApi: T.ICustomApiSettingsTypes = {
    name: 'Monthly report',
    requestMethod: T.ERequestMethod.GET,
    path: '/reports/monthly',
    apiAccessType: T.EAPIAccessType.TOKEN_ACCESS,
    separateSandboxSettings: {
        enableSeparateSandboxForThis: 'reports',     // the group
        runtime: 'bun',                              // another runtime of the language of the code
        version: '1.4',
        sandboxCount: 1,
        packages: {
            allowAllPackagesOfAdmin: true,           // the packages of the Sandbox Settings, and :
            sandboxPackages: [{ name: 'pdfkit', version: '0.15.0' }],
        },
        // dockerFileOfSandbox: 'FROM {{AM_BASE_IMAGE}}\nRUN apt-get … \n{{AM_PACKAGES}}\n{{AM_RUNNER}}',
    },
};
Key Meaning
enableSeparateSandboxForThis The name of the group. Empty : the sandboxes of the language.
runtime, version A runtime of the language of the code (node or bun for TypeScript) and a tag of its image. The ones of the Sandbox Settings when absent.
sandboxCount The most sandboxes of the group at a time, on each server.
packages.sandboxPackages The packages of the group, from the registry of its language.
packages.allowAllPackagesOfAdmin true : the packages of the Sandbox Settings too. A package named in both is installed once, in the version of the group.
dockerFileOfSandbox A Dockerfile of the group, with the same markers.
  • The group gets an image of its own (shared with any account which has the same settings), built when the API is saved.
  • Changing the settings of a group starts its sandboxes anew on every server.