# Remove by ID API (schema)

> Delete one row by its primary key or any column with the schema remove by id API of API Maker, and get the removed row back, with select and deep.

Source: https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-remove-by-id-api.html

Deletes one row and answers with the row as it was, so the caller can show or log what disappeared.

| | |
|---|---|
| Method | DELETE |
| URL | `/api/schema/admin/mysql8/inventory/customers/:id[/:primaryKey]` |
| Body | none |
| Query params | [select](https://docs.apimaker.dev/v1/docs/apis-all/query-params/select.html), [deep](https://docs.apimaker.dev/v1/docs/apis-all/query-params/deep.html), 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.removeById`](https://docs.apimaker.dev/v1/examples/sys/db/removeById.html) |
| API id | `SCHEMA_DEL_DELETE_BY_ID` (groups, settings, hooks, WebSocket subscriptions) |
| The other family | [Remove by id as a generated API](https://docs.apimaker.dev/v1/docs/apis-all/generated-apis/auto-generated-remove-by-id-api.html) |

> **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/v1/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/: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

```text
DELETE /api/schema/admin/mysql8/inventory/customers/1
```

**Answer**

```json
{
    "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/schema/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](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-remove-by-query-api.html).

## From your code

[`g.sys.db.removeById`](https://docs.apimaker.dev/v1/examples/sys/db/removeById.html) 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](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) instead of `data`.

## Headers

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

## Related

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