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

Save single or multiple (schema API)

Inserts one row (an object) or many (an array) and answers 201 with what was saved, ids included.
Method POST
URL /api/schema/admin/mysql8/inventory/customers/save-single-or-multiple
Body one object, or an array of objects
Query params select, deep : applied to the answer
Answer 201 and data : the saved row, or the array of saved rows
Databases MongoDB, MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, TiDB, Percona
Cached no (a write ; it resets the cache of the table)
From code g.sys.db.saveSingleOrMultiple
API id SCHEMA_POST_BULK_INSERT (groups, settings, hooks, WebSocket subscriptions)
The other family Save single or multiple as a generated API

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.

The URL

/api/schema/admin/mysql8/inventory/customers/save-single-or-multiple : replace admin with the user path of your account, mysql8 with your instance, inventory with the database and customers with the table. The examples use this table :

customer_id first_name last_name last_update pincode isActive
1 Bob lin 2022-11-14 04: 34: 58 382345 1
2 Alice Page 2022-10-15 02: 10: 40 382346 1
3 Mallory Brown 2022-09-13 03: 44: 05 382347 1
4 Eve Mathly 2022-11-12 01: 59: 33 382348 1
5 Eve Page 2022-11-12 01: 59: 33 382349 1

One row

POST /api/schema/admin/mysql8/inventory/customers/save-single-or-multiple
Body
{ "first_name": "Bob", "last_name": "Lin", "pincode": 382345 }
Answer
{
    "success": true,
    "statusCode": 201,
    "data": { "customer_id": 6, "first_name": "Bob", "last_name": "Lin", "pincode": 382345 }
}
  • The primary key can be sent ("customer_id": 27) or left out : the database or API Maker generates it (isAutoIncrementByDB, isAutoIncrementByAM, isAutoGenerateByAM in the schema, _id on MongoDB).

Many rows

Body
[
    { "first_name": "Bob", "last_name": "Lin" },
    { "customer_id": 29, "first_name": "Eve", "last_name": "Page" }
]
  • The answer is an array in the same order. Objects with and without a primary key can mix.
  • Every row is checked before anything is written ; an error names the object with dataIndex.

What the schema does to each row

  • Unknown keys are refused, values converted to their types, strings trimmed and cased, conversionFun run, fields encrypted or hashed, ids and defaults filled, then the rules and validatorFun run. Every error is returned at once with 400 and nothing is saved. See Table schema.
  • A field with a relation (collection and column in the schema) accepts a nested object : it is saved to its table first and replaced by its id. A failure reverts the rows saved so far. For nested updates and arrays, see master save.
Body : the state is saved to the states table, then the city
{ "city_name": "Wembley", "state_id": { "state_name": "London", "country_id": 302 } }

The answer you want

POST /api/schema/admin/mysql8/inventory/customers/save-single-or-multiple?select=customer_id,first_name
POST /api/schema/admin/mysql8/inventory/customers/save-single-or-multiple?deep=[{s_key:'shipping_id',t_col:'shippings',t_key:'id'}]
  • select keeps only some fields of the saved rows in the answer ; deep populates their relations.

After the save

  • The cache of the table is reset, subscribed WebSocket clients are notified, events with an automatic trigger on this API run, and post hooks get the saved rows in g.res.output.

From your code

g.sys.db.saveSingleOrMultiple makes the same call from custom APIs, hooks, events, schedulers and test cases, with the same headers and params. Pass true as the second argument to get the whole response envelope instead of data.

Headers

Every call takes the request headers : the tokens, x-am-response-case, x-am-content-type-response (JSON, XML, YAML…), x-am-response-object-type: make_flat, x-am-cache-control, x-am-get-encrypted-data, x-am-internationalization, x-am-tenant-username, x-am-meta.

Errors

Code When
401 The token in x-am-authorization is missing or invalid.
403 No group of the API user grants this API of this table, or a field of the request.
404 The instance, database or table of the URL does not exist, or the table has no schema (use /api/gen).
400 The query or the body is wrong : the error messages say which key and why.