# `jadpo api`

Rewrite the API records.

`update` rewrites each API's committed record, api/<api>.jadpo_record, from the routes (areas 7 and 18): every route, the fields it takes and sends, and the failure codes it can answer with. The OpenAPI document's version is a hash of the record. jadpo check fails while a record disagrees with the routes, so every change to an API is a diff of one file to review and commit with the code. A record under its old name, api/<api>.api, is removed.

```text
jadpo api <action>
```

## Arguments

- `action`: What to do: update

## On every command

- `--json`: Print data for tools instead of text
- `--full`: Show everything a report shortens
- `--help`: Show every flag, with examples
- `--color <when>`: Choose when to use colour

`jadpo api --json` writes one JSON document to standard output instead of text, with the same exit code. The document has `schemaVersion`, `command` (`"api"`), `ok`, `data` (what the command produced, `null` when it failed) and `diagnostics` (each error with its `rule`, `reason`, `next` and `help`). A command that needs a terminal refuses `--json` and names the flags that do the same job.

## Examples

```text
# Bring every API record up to date with the routes
jadpo api update
```

## Errors

- [`cli.api_arguments`](/docs/errors/cli.api_arguments.md): A `jadpo api` command names no action, one it doesn't have, or more than `update`
- [`toolchain.artifact_write_failed`](/docs/errors/toolchain.artifact_write_failed.md): A file Jadpo writes for you, such as a record, couldn't be written, usually because it or its folder is read-only
- [`toolchain.project_not_found`](/docs/errors/toolchain.project_not_found.md): You ran a command that works on a project in a folder with no `app.jadpo`, in it or in any folder above it