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

Replace by id (schema API)

Replaces one MongoDB document with the body : fields you do not send are gone. For a partial change, use update by id.
Method PUT
URL /api/schema/admin/mongodb/inventory/customers/replace-by-id/:id[/:primaryKey]
Body the whole new document
Query params select, deep, upsert, returnDocument, throwErrorIfRecordNotFound
Answer data : the document after the change (or before, with returnDocument=before)
Databases MongoDB only
Cached no (a write ; it resets the cache of the table)
From code g.sys.db.replaceById
API id SCHEMA_PUT_REPLACE_BY_ID (groups, settings, hooks, WebSocket subscriptions)
The other family Replace by id 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/mongodb/inventory/customers/replace-by-id/:id[/:primaryKey] : replace admin with the user path of your account, mongodb 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

PUT /api/schema/admin/mongodb/inventory/customers/replace-by-id/60ae24c8c37cd955cc144162
Body
{ "customer_id": 1, "first_name": "Rex", "last_name": "Nestor", "pincode": 879654, "isActive": 0 }
  • The document keeps its _id and gets exactly these fields. A field of the old document which is not in the body disappears.
  • By another column : /replace-by-id/4/customer_id.

Options

  • ?upsert=true inserts the document when the id does not exist.
  • ?returnDocument=before answers the old document.
  • ?throwErrorIfRecordNotFound=true answers 404 instead of data: null for an unknown id.
  • select and deep shape the answer.

What the schema does

  • The body is treated as a full save : conversions, defaults, generated values and every rule apply, required fields must all be there, and the version field of optimistic concurrency control must match the document.

SQL tables

  • Replace by id exists only on MongoDB (Replace by id API is not supported for instance type … otherwise). On a SQL table, update by id with every column does the same.

From your code

g.sys.db.replaceById 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.