# Master Save API

> Save or update a tree of related objects in one call with the master save API of API Maker - each object is inserted or updated by its primary key, nested objects go to their own tables, arrays fill one-to-many relations, and a failure reverts everything.

Source: https://docs.apimaker.dev/v4/docs/apis-all/schema-apis/auto-generated-schema-based-master-save-api.html

One call which saves or updates a whole object graph : each object is inserted when it has no primary key and updated when it has one, at every level of nesting, across tables and even databases.

| | |
|---|---|
| Method | POST |
| URL | `/api/schema/admin/mysql8/inventory/customers/master-save` |
| Body | one object, or an array of objects, with nested related objects |
| Query params | [select](https://docs.apimaker.dev/v4/docs/apis-all/query-params/select.html), [deep](https://docs.apimaker.dev/v4/docs/apis-all/query-params/deep.html) : applied to the answer |
| Answer | `201` and `data` : the saved object(s), with the ids of the nested 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.masterSave`](https://docs.apimaker.dev/v4/examples/sys/db/masterSave.html) |
| API id | `SCHEMA_MASTER_SAVE` (groups, settings, hooks, WebSocket subscriptions) |
| Without a schema | `/api/gen/admin/mysql8/inventory/customers/master-save` : [below](https://docs.apimaker.dev/v4/docs/apis-all/schema-apis/auto-generated-schema-based-master-save-api.html#without-a-schema) |

> **Generated (`/api/gen`) or schema (`/api/schema`) ?**
>
> Both families offer the same operations on the same URL pattern. The **schema APIs** read the [schema](https://docs.apimaker.dev/v4/docs/schema/schema.html) 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/master-save` : 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        |

## Save or update

```text
POST /api/schema/admin/mysql8/inventory/customers/master-save
```

**Body : no primary key, inserted**

```json
{ "first_name": "Bob", "last_name": "Lin" }
```

**Body : a primary key which exists, updated with these fields**

```json
{ "customer_id": 27, "pincode": 382330 }
```

- The rule is the same at every level : **primary key present, the row is read and updated ; absent, the row is inserted.** An update sends only the fields you give.
- An array in the body saves or updates each object and answers an array.

## A tree of objects

With relations in the schemas (`collection`, `column`, `database`, `instance` on a field), a nested object is saved or updated in its own table first and its id is written in the parent :

**Body : three tables, one call**

```json
{
    "city_name": "Wembley",
    "state_id": {
        "state_name": "London",
        "country_id": { "country_name": "UK" }
    }
}
```

**Answer**

```json
{
    "success": true,
    "statusCode": 201,
    "data": { "id": 107, "city_name": "Wembley", "state_id": 205 }
}
```

- The country is saved first, its id goes into the state, the state is saved, its id goes into the city. The tables can be in different databases and instances : the relation says where.

> Diagram : Master save : the deepest object first, its id goes up into its parent
>
> Master save of a city with its state and its country : the deepest object is saved first. The country is inserted and its id goes into the state, the state is inserted and its id goes into the city, then the city is saved. A failure on the way reverts every row the call wrote.

- `deep` on the call gives the nested rows back populated : `?deep=[{s_key:'state_id',deep:[{s_key:'country_id'}]}]`.

## One to many with virtual fields

A [virtual field](https://docs.apimaker.dev/v4/docs/schema/schema.html) (`isVirtualField` with `s_columnVirtualLinker` and `t_columnVirtualLinker`) takes an array : each item is saved or updated in the target table with the key of the parent.

**Body : an order and its items**

```json
{
    "order_no": 1001,
    "customer_id": 1,
    "items": [
        { "product_id": "66fa1c9a9b1e4a0012a3c002", "qty": 2 },
        { "id": 55, "qty": 3 }
    ]
}
```

- The first item is inserted, the second (it has its primary key) is updated.

## When something fails

- Every row written by the call is reverted when a later one fails : a wrong field in the country of the example above leaves no city and no state behind.
- The errors name the object and the field, with `dataIndex` for arrays.

## Optimistic concurrency control

- A table whose schema has a version field (`isConcurrencyControlField`) requires the version in every update of master save, and refuses a stale one with `400`. See [Optimistic concurrency control](https://docs.apimaker.dev/v4/docs/features/optimistic-concurrency-control.html).

## From your code

[`g.sys.db.masterSave`](https://docs.apimaker.dev/v4/examples/sys/db/masterSave.html) makes the same call from custom APIs, hooks, events, schedulers and test cases, with the same headers and params. To get the whole [response envelope](https://docs.apimaker.dev/v4/docs/apis-all/response-format.html) instead of `data`, pass `true` as the second argument in TypeScript, or call it through `g.sys.db.full` in the other languages.

## Without a schema : /api/gen

Every table also answers this operation under `/api/gen`, with or without a schema :

| | |
|---|---|
| URL | `/api/gen/admin/mysql8/inventory/customers/master-save` |
| API id | `GEN_MASTER_SAVE` (groups, settings, hooks, WebSocket subscriptions) |
| From code | [`g.sys.db.gen.masterSaveGen`](https://docs.apimaker.dev/v4/examples/sys/db/masterSave.html#without-a-schema) |

The data passes as it is : nothing is converted, validated, defaulted, encrypted or numbered, and a filter matches the type you send (`"22"` does not match the number `22`). On MongoDB, strings which look like ObjectIds are converted. The query params, headers and errors are the ones of this page.

- Without relations, a nested object is stored as an embedded document on MongoDB and refused on SQL. The tree of tables needs the schema API above.
- Save or update by primary key works : `_id` on MongoDB, the primary key column on SQL.

## Headers

Every call takes the [request headers](https://docs.apimaker.dev/v4/docs/apis-all/header/requestHeader.html) : 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](https://docs.apimaker.dev/v4/docs/apis-all/error-codes.html) say which key and why. |

## Related

- [All APIs at a glance](https://docs.apimaker.dev/v4/docs/apis-all/overview.html) · [Query params](https://docs.apimaker.dev/v4/docs/apis-all/query-params/query-params.html) · [Response format](https://docs.apimaker.dev/v4/docs/apis-all/response-format.html) · [Pre hooks](https://docs.apimaker.dev/v4/docs/apis-all/hooks/preHook-api.html) and [post hooks](https://docs.apimaker.dev/v4/docs/apis-all/hooks/postHook-api.html) · [Automatic caching](https://docs.apimaker.dev/v4/docs/features/automatic-caching.html)
- [Table schema](https://docs.apimaker.dev/v4/docs/schema/schema.html) : what the conversions and validations do to every write.