# Keeping requests in step with the spec

Source: https://api-genie.dev/docs/reference/cli/test/sync
Part of the reference of [test](https://api-genie.dev/docs/reference/cli/test.md).
Its other pages: [Request files](https://api-genie.dev/docs/reference/cli/test/requests.md), [Variables and OAuth 2](https://api-genie.dev/docs/reference/cli/test/variables.md), [Assertions and scripts](https://api-genie.dev/docs/reference/cli/test/assertions.md), [Validation](https://api-genie.dev/docs/reference/cli/test/validation.md), [Generated requests](https://api-genie.dev/docs/reference/cli/test/generate.md), [GraphQL requests](https://api-genie.dev/docs/reference/cli/test/graphql.md), [WebSocket and MQTT requests](https://api-genie.dev/docs/reference/cli/test/websocket-mqtt.md), [Kafka requests](https://api-genie.dev/docs/reference/cli/test/kafka.md), [AMQP requests](https://api-genie.dev/docs/reference/cli/test/amqp.md), [gRPC requests](https://api-genie.dev/docs/reference/cli/test/grpc.md), [Importing collections](https://api-genie.dev/docs/reference/cli/test/import.md), [httpYac compatibility](https://api-genie.dev/docs/reference/cli/test/httpyac.md).

`apigenie test sync` (since 0.13.0) checks the requests of `.http` files that `# @operation` binds to
an OpenAPI or Swagger 2.0 document against it. It reports which requests are in sync, which drifted,
which are bound to an operation that is gone, and which operations have no request yet. With
`--write`, it merges the document into the requests and keeps what you wrote: your values,
`{{variables}}`, scripts, assertions and comments stay, and only what the document changed is taken.

```sh
apigenie test sync --spec SPEC [--write] [--base FILE | --base-rev REV] FILES...
```

The options of `sync` go after `sync`: `apigenie test --timeout 5 sync ...` is refused, since
`--timeout` before `sync` is an option of a test run.

| Option | Meaning |
| --- | --- |
| `FILES` | `.http` and `.rest` files, or directories to search for them; at least one, required |
| `--spec SPEC` | The OpenAPI 3.x or Swagger 2.0 document the requests are bound to; required |
| `--write` | Merge the document into the request files, and keep it in `--base` as the base of the next merge. Off by default: the files are only checked |
| `--base FILE` | Where the merge base is kept. Default: `http-sync-base.json` in the first directory of `FILES`, else next to the first file |
| `--base-rev REV` | Take the merge base from a Git revision of `--spec` (a commit, a branch, a tag) instead of `--base`; nothing is kept |
| `--json` | Print the [status of the run](/docs/reference/cli#json-output) as JSON, with the report in its `output` |

## An example

The requests in `requests/pets.http` were written for the first version of `openapi.yaml`, and
`requests/http-sync-base.json` holds that version, kept there by the `--write` that last brought
them in step:

```http
### list
# @operation listPets
GET {{host}}/pets?limit=5&sort=name&debug=1

### create
# @operation createPet
POST {{host}}/pets
Content-Type: application/json

{"name": "{{petName}}", "age": "4"}

### ping
GET {{host}}/ping
```

The second version of `openapi.yaml` drops the `sort` query parameter, adds a required `tenant`
one (`example: acme`), turns `age` into an integer (`example: 3`) and adds `DELETE
/pets/{petId}` (`deletePet`). `debug` was in neither version: you added it.

```sh
apigenie test sync --spec openapi.yaml requests
```

```text
requests/pets.http:3: drifted: list: the query parameter sort is no longer in the spec (--write merges it)
requests/pets.http:3: drifted: list: the query parameter debug is not in the spec (merge it by hand)
requests/pets.http:3: drifted: list: the query parameter tenant is required by the spec and missing (--write merges it)
requests/pets.http:10: drifted: create: /age of the body is integer in the spec, not a string (--write merges it)
requests/pets.http:13: local only: ping (no # @operation)
no request: deletePet (DELETE /pets/{petId})
0 in sync, 2 drifted, 0 bound to a gone operation, 1 local only; 1 operations without a request
Merge base: requests/http-sync-base.json
```

Each line about a request names the file, the line it is about (the request line, a header, the
body or the `# @operation`), the request's status, its `# @name` (else its `###` title, else its
method and URL) and the difference.

## The report

Each HTTP request of the files is one of:

- **in sync** with its operation;
- **drifted**, with a line for each difference;
- bound to an operation that is **gone** from the document, with the operation its URL matches, if
  one does;
- **local only**: it has no `# @operation`, or has `# @operation off`.

The operations with an `operationId` that no request is bound to are listed after them; one that
a rename `--write` merges would bind a request to counts as bound. `WS`, `MQTT`, `KAFKA`, `AMQP`,
`GRAPHQL` and `GRPC` regions are left out.

What is compared:

- the method;
- the path, by its last segments against the operation's path template: a server's base path
  or a `{{host}}` before it doesn't matter, and a `{{variable}}` matches any parameter;
- the query parameters: one the document doesn't declare, and a required one that is missing;
- the headers: a required header parameter that is missing and, with a merge base, a header that
  the base declared as a parameter and the document no longer does. Other headers are yours;
- whether the operation takes a request body, and whether it requires one;
- a JSON body, property by property: properties the schema doesn't declare, values of another
  type, enum values it doesn't allow, and required properties that are missing. A schema with
  `properties` and no `additionalProperties` (or `additionalProperties: false`) declares only
  those; `additionalProperties: true` or a schema allows any other. `allOf` is merged. For
  `oneOf` and `anyOf`, the body is checked against the branch that declares most of its
  properties, and a matching `const` or `enum` (a discriminator) counts more.

## The merge base

A parameter or a property that the document doesn't declare is either yours (added on purpose,
or a value of another type to test an error) or one the document dropped. Only the previous
version of the document tells them apart, so the merge takes it as its base. `--write` keeps the
document, bundled as JSON, in `http-sync-base.json`. Commit that file with the request files, so
that every machine and CI merge from the same base. The base belongs to the files as a whole:
sync the same files each time.

`--base-rev v1.4.0` takes the base from Git instead: the `--spec` file as it was at that revision.
The references of that file to other local files are read from the working tree, not from the
revision.

Without a base, as on the first run, nothing you wrote is removed or replaced: what the document
doesn't declare is reported as `merge it by hand` and stays. `--write` then only adds what the
document requires (required query and header parameters, required body properties, a required
body) and keeps the document as the base of the next merge.

## What `--write` merges

The drift reported as `--write merges it`:

- the method and the path of an operation the document moved (with a base), keeping the values
  of the path parameters by name and the part of the path before the operation's;
- query parameters and header parameters the document dropped (with a base) are removed;
  required ones it added are added, with the values [`--generate`](/docs/reference/cli/test/generate)
  makes;
- a JSON body keeps your values and `{{variables}}`. With a base, properties the document no
  longer declares are removed, and a value whose type the document changed, or an enum value it
  dropped, is replaced. Required properties are added and, with a base, so are the properties
  the document added (from the schema's examples, else generated);
- a body the operation now requires is added, and one it no longer takes (with a base) is
  removed;
- a request bound to an operation that the base had at the same method and path, under another
  `operationId`, gets the new one in its `# @operation`, unless another request is already bound
  to it.

What is reported as `merge it by hand` stays as it is:

- without a base, everything but a missing required value;
- with a base, what the base didn't declare either: a parameter (a name that an object
  parameter only took as any property counts as undeclared), a property, a value of another type
  than the base's, an enum value, a method or a path;
- an operation that is gone, or one renamed to an `operationId` another request is already
  bound to;
- a body the operation no longer takes in a `< file`, or of a media type the document doesn't
  take;
- a JSON body that doesn't parse or repeats a property;
- a value the document requires, adds or changed that can't be made from it (no example, and
  no schema to generate one from, or an object with no properties to fill in).

Only the lines that change are rewritten: the request line with its `?` and `&` lines, a header,
the body. Line ends and the rest of the file stay. A JSON body that changes is written compact,
without spaces, when it was on one line, else indented like it was.

With `--write`, each merged difference is printed as `merged:` instead of `drifted:`, each
rewritten file as `FILE: written`, and the counts are those before the merge. The last lines say
where the merge base came from (`Merge base: FILE`, `Merge base: git REV:PATH`, or `No merge base
(FILE not found): ...`) and, when the base file changed, that the document was kept in it:

```text
requests/pets.http:3: merged: list: the query parameter sort is no longer in the spec
requests/pets.http:3: drifted: list: the query parameter debug is not in the spec (merge it by hand)
requests/pets.http:3: merged: list: the query parameter tenant is required by the spec and missing
requests/pets.http:10: merged: create: /age of the body is integer in the spec, not a string
requests/pets.http:13: local only: ping (no # @operation)
requests/pets.http: written
no request: deletePet (DELETE /pets/{petId})
0 in sync, 2 drifted, 0 bound to a gone operation, 1 local only; 1 operations without a request
Merge base: requests/http-sync-base.json
Kept the spec in requests/http-sync-base.json as the base of the next merge; commit it with the requests
```

The requests are then:

```http
### list
# @operation listPets
GET {{host}}/pets?limit=5&debug=1&tenant=acme

### create
# @operation createPet
POST {{host}}/pets
Content-Type: application/json

{"name":"{{petName}}","age":3}

### ping
GET {{host}}/ping
```

When a request file can't be read or written, the other files are still checked and written, but
the merge base is not updated.

## Exit status

| Code | Meaning |
| --- | --- |
| 0 | Every request bound to an operation is in sync; with `--write`, all the drift was merged |
| 1 | A request drifted or is bound to an operation that is gone; with `--write`, one has drift to merge by hand |
| 2 | No `--spec` or no `FILES`, a path of `FILES` that doesn't exist, `--spec` or the merge base can't be read, `--base-rev` can't be read from Git, `--base` with `--base-rev`, an option of the test run before `sync`, a request file that can't be read or written, the merge base that can't be written, or an unexpected error |

## Not yet

- New enum values are not added as disabled entries, since `.http` has no disabled values.
- Bodies other than JSON, and `< file` bodies, are only checked for being required or gone.
- Cookies and the values of URL parameters are not compared.
