influx-cli/api/contract/README.md

API Contract

This directory contains the source YMLs used to drive code generation of HTTP clients in api.

YML Structure

Most YMLs used here are pulled from the source-of-truth openapi repo via a git submodule. In rare cases, the full description of an API is too complex for our codegen tooling to handle; the overrides/ directory contains alternate definitions for paths/schemas that work around these cases. cli.yml ties together all the pieces by linking all routes and schemas used by the CLI.

Updating the API contract

To extend/modify the API contract used by the CLI, first make sure the openapi submodule is cloned and up-to-date:

# Run from the project root.
git submodule update --init --recursive

Then create a new branch to track your work:

git checkout <new-branch-name>

Next, decide if any modifications are needed in the source-of-truth openapi repo. If so, create a branch in the submodule to track changes there:

cd api/contract/openapi && git checkout -b <new-branch-name>

Edit/add to the files under api-contract/ to describe the new API contract. Run the following from the project root test your changes and see the outputs in Go code:

make openapi
# Use `git status` to see new/modified files under `api`

Once you're happy with the new API contract, submit your changes for review & merge. If you added/edited files within openapi, you'll first need to:

1. Push your submodule branch to GitHub

   cd api/contract/openapi && git push <your-branch-name>
   

2. Create a PR in openapi, eventually merge to master there
3. Update your submodule to point at the merge result:

   cd api/contract/openapi && git fetch && git checkout master && git pull origin master
   

4. Update the submodule reference from the main repo:

   git add api/contract/openapi
   git commit