# Get by ID API (generated)

> Read one row by its primary key with the generated get by id API of API Maker, or by any other column with the primaryKey param, with select and deep populate.

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

Reads one row by its primary key, or by any other column with the second param. With `select` and `deep`, it is the detail screen of your app in one call.

| | |
|---|---|
| Method | GET |
| URL | `/api/gen/admin/mysql8/inventory/customers/get-by-id/:id[/:primaryKey]` |
| Body | none |
| Query params | [select](/v1/docs/apis-all/query-params/select.html), [deep](/v1/docs/apis-all/query-params/deep.html), find (extra conditions) |
| Answer | `data` : the row, or `null` when nothing matches |
| Databases | MongoDB, MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, TiDB, Percona |
| Cached | yes, with `enableCaching` on the table |
| From code | [`g.sys.db.gen.getByIdGen`](/v1/examples/sys/db/gen/getByIdGen.html) |
| API id | `GEN_GET_BY_ID` (groups, settings, hooks, WebSocket subscriptions) |
| The other family | [Get by id as a schema API](/v1/docs/apis-all/schema-apis/auto-generated-schema-based-get-by-id-api.html) |

!!! info "Schemaless : the data passes as it is"
    The generated APIs never read the [schema](/v1/docs/schema/schema.html) 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/get-by-id/: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        |

## By primary key

```text
GET /api/gen/admin/mysql8/inventory/customers/get-by-id/1
```

```json
{
    "success": true,
    "statusCode": 200,
    "data": { "customer_id": 1, "first_name": "Bob", "last_name": "lin", "last_update": "2022-11-14T04:34:58.000Z", "pincode": 382345, "isActive": 1 }
}
```

- The primary key is the one of the table (`_id` on MongoDB, the primary key column on SQL, or `isPrimaryKey` in the schema). An unknown id answers `data: null` with `success: true`.

## By any column

Name the column as the second param :

```text
GET /api/gen/admin/mysql8/inventory/customers/get-by-id/Bob/first_name
GET /api/gen/admin/mysql8/inventory/customers/get-by-id/382345/pincode
```

- When several rows match, the first one is returned.
- The value is converted to the type of the column, so `382345` is compared as a number.

## Fields and related rows

```text
GET /api/gen/admin/mysql8/inventory/customers/get-by-id/1?select=first_name,last_name
GET /api/gen/admin/mysql8/inventory/customers/get-by-id/1?deep=[{s_key:'customer_id',t_col:'orders',t_key:'customer_id',isMultiple:true}]
```

- `deep` works as on [get all](/v1/docs/apis-all/generated-apis/auto-generated-get-all-api.html#related-rows-with-deep), with the relations of the schema when the table has one.

## One more condition

`find` narrows the match further, for example to make sure the row belongs to the caller :

```text
GET /api/gen/admin/mysql8/inventory/customers/get-by-id/1?find={isActive:1}
```

- A pre hook can add such a condition to `g.req.query.find` for every call : the row scoping pattern of [Handle role based permissions](/v1/docs/authorization/handle-role-based-permissions.html).

## From your code

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

## Headers

Every call takes the [request headers](/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. |
| `400` | The query or the body is wrong : the [error messages](/v1/docs/apis-all/error-codes.html) say which key and why. |

## Related

- [All APIs at a glance](/v1/docs/apis-all/overview.html) · [Query params](/v1/docs/apis-all/query-params/query-params.html) · [Response format](/v1/docs/apis-all/response-format.html) · [Pre hooks](/v1/docs/apis-all/hooks/preHook-api.html) and [post hooks](/v1/docs/apis-all/hooks/postHook-api.html) · [Automatic caching](/v1/docs/features/automatic-caching.html)