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

Remove by id (generated API)

Deletes one row and answers with the row as it was, so the caller can show or log what disappeared.
Method DELETE
URL /api/gen/admin/mysql8/inventory/customers/:id[/:primaryKey]
Body none
Query params select, deep, throwErrorIfRecordNotFound, find
Answer data : the removed row, or null when no row matched
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.gen.removeByIdGen
API id GEN_DEL_DELETE_BY_ID (groups, settings, hooks, WebSocket subscriptions)
The other family Remove by id as a schema API

Schemaless : the data passes as it is

The generated APIs never read the schema of the table. Nothing is converted, validated, defaulted, encrypted or numbered : what you send is what the database gets, and a filter matches the type you send ("22" does not match the number 22). On MongoDB, strings which look like ObjectIds are converted. Every table has these APIs, with or without a schema ; the same operations under /api/schema apply the schema.

The URL

/api/gen/admin/mysql8/inventory/customers/:id[/:primaryKey] : 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

The call

DELETE /api/gen/admin/mysql8/inventory/customers/1
Answer
{
    "success": true,
    "statusCode": 200,
    "data": { "customer_id": 1, "first_name": "Bob", "last_name": "lin", "pincode": 382345, "isActive": 1 }
}
  • The id is the primary key. DELETE /api/gen/admin/mysql8/inventory/customers/Bob/first_name removes the first row whose first_name is Bob.

Options

  • ?select=first_name and ?deep=[…] shape the returned row (deep populates it before it is removed).
  • ?throwErrorIfRecordNotFound=true answers 404 and Record not found. for an unknown id ; the default is data: null.
  • ?find={isActive:0} adds a condition : the row is removed only when it matches. A pre hook can add such a condition to keep callers to their own rows.

After the call

  • The cache of the table is reset, WebSocket subscribers are notified, post hooks receive the removed row in g.res.output.
  • To remove many rows at once, use remove by query.

From your code

g.sys.db.gen.removeByIdGen 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.
400 The query or the body is wrong : the error messages say which key and why.