Children first, parents after
The deepest object is saved first. Its new id replaces the object in its parent, which is saved next, and so on.
Database APIs
Master Save
Save a whole tree of related objects in one call, across tables and databases.
Send a city with its state and the country of that state as nested objects. API Maker saves the deepest object first, puts its new id in the parent, and goes up to the top. Objects that carry their key are updated instead. If a step fails, what was saved is removed and what was updated is restored.
See it live
Step through it, slow it down, or open the full canvas.
api-maker/features/master-saveLive- Databases
- 3in one call
- Rows saved
- 0this call
- API calls
- 0from the app
- Last status
- –HTTP
Send the whole tree in one call. A city, its state and the country of that state, as nested objects. The schema knows which table, database and type each goes to.
How it works
Send the whole tree in one call.
A city, its state and the country of that state, as nested objects. The schema knows which table, database and type each goes to.
The deepest object is saved first.
The country goes to PostgreSQL and gets id 303. In the payload, the object is replaced by that id.
Each parent is saved with the ids of its children.
The state is saved in SQL Server with country_id 303 and gets id 204, which takes its place in turn.
Three databases, one call, one answer.
The city is saved in MySQL with state_id 204 and the API answers 201 Created with the saved row.
Objects with their key are updated.
The state carries id 201 and its row exists: it is updated, its old values kept as a backup, and the new city points to it.
A failure reverts everything.
The city has no city_name: after its country and state were saved, it fails validation. Both are deleted again and the API answers 400.
What you get
Insert or update, per object
An object without its primary key is inserted. An object with its key is updated, and its old values are kept to revert it if needed.
All or nothing
When any object fails, for example on validation, the rows saved by the call are deleted and the updated ones restored, then the error is returned.
Any mix of databases
The schema says where each nested object goes, so one payload can write to MySQL, SQL Server and PostgreSQL.
Validated on the way
Every object is converted and validated with the schema of its own table before it is written.
Children lists too
With virtual fields, a parent can carry the array of its children, like an invoice with its lines, in the same payload.
An example
An invoice form
A form creates an invoice with its lines and a new customer at once. One master save writes the customer, the invoice and every line in the right order. If one line is invalid, nothing of it stays in the database.
POST /api/schema/admin/mysql/geo/cities/master-savex-am-authorization: <API user token>{ "city_name": "Wembley", "state_id": { "state_name": "London", "country_id": { "id": 302, "country_name": "UK" } }}The country has its id, so it is updated. The state has none, so it is inserted and its new id goes into the city.
Good to know
- Master save follows the relations of the schema: use it on schema APIs. Without a schema, the call only saves the top objects, like save single or multiple.
- The revert is done by API Maker, not by a database transaction: other requests can read the new rows until they are reverted, and a revert that fails is reported in the errors.
Questions
How is it different from save single or multiple?
Save inserts the objects you send into one table. Master save walks the nested objects into their own tables, inserts or updates each one, and links them with the new ids.
Can I send many trees at once?
Yes. Send an array: every item is saved with its own nested objects.
What does the answer contain?
The saved top object with 201 Created. Add select or deep to the call to shape what comes back.
Learn more
Documentation