api/contrib/README.md

# contrib/

This folder provides some functionality that may not be 100% supported yet.
Things here may break at any time and are not necessarily expected to be updated before the breaking changes are accepted.


## gen_call_scripts, call_templates/ and call_scripts/

The `call_templates` directory contains a set of example json input files for making api calls.
The `call_scripts` directory is an ignored directory generated by the `gen_call_scripts` script.
`gen_call_scripts` will create scripts of the form `service__method` that call their corresponding endpoint.
They look for `service__method_input.json` files and write to `service__method_output.json` in the call_scripts directory.

### Getting Started

To do the generation:

```bash
cd ~/chromiumos/chromite/api/contrib/
./gen_call_scripts
```

Then to run a specific endpoint (e.g. chromite.api.VersionService/Get):

```bash
cd call_scripts/
./version__get
```

Which will produce something like:

```text
Running chromite.api.VersionService/Get
13:16:21: DEBUG: Services registered successfully.
Completed chromite.api.VersionService/Get
Success!
Return Code: 0
Result:
{
  "version": {
    "major": 1
  }
}
```

Everything between `Running ...` and `Completed ...` in the output is the output produced by the endpoint itself.
The `Result:` portion is simply the output.json file contents, e.g. `cat version__get_output.json`.

### Non-execution Runs

The Build API supports a validate-only calls that only validates the provided input,
and mock calls to mock a validation input failure, or provide static mock success or failure outputs without actually executing the endpoint.
These call types allow validating the implementation of a caller against the version of the API it is calling.
For example, the CI recipes will eventually be able to use them to validate the recipes against factory and firmware branches even as we.
These are *not* expected to be terribly useful for manual executions,
but calls with the options set in the API config option to validate their behavior is supported.

By default, it will generate an execution config (i.e. run the endpoint).


### Contributing New Templates

The example templates are just JSON formatted request proto messages.
Currently, only one per endpoint is supported for the generation process,
but providing multiple examples is encouraged for manual use when it makes sense.

`gen_call_scripts` has a `-b`/`--build-target` option that is used when generating the inputs from the example files.
The option allows generating your input files and substituting in a specific build target everywhere.
In order to support this feature, simply replace a specific build target name in the example input (e.g. `"betty"`) with `"%(build_target)s"`.

The templates also support two other variables to make adding generic templates easier: `chroot` and `src_root`.
The `chroot` variable subs in the full, default path to the chroot.
The `src_root` variable subs in the path to your checkout, which is typically somewhere like `~/chromiumos`.

### Notes

The `call_scripts/` input files are only overwritten when generating for a new build target (`-b`/`--build-target`), or using the `--force` option.
The only exception is that new templates in `call_templates/` will replace empty inputs (i.e. those containing just `{}`),
which is what `gen_call_scripts` produces when it has no example input file.
`call_scripts/` may be deleted at any time and will be regenerated from scratch,
you will only lose any custom input files and any previously generated output files.

You must be aware of the context of the endpoints for everything to work properly.
These scripts only provide a more convenient way to call the endpoints, there is no automatic precondition checking or running.
For example, you must manually run the endpoints to create the sysroot and build packages before running `image__create`.
The endpoints are capable of using an existing sysroot, but compatibility is not guaranteed.
This is especially true for endpoints that have specific USE flags that differ from those used to build out your sysroot.
Often endpoints that are extracting data (e.g. the ArtifactsService) will work with any existing sysroot.