boundary/internal/adding-a-new-field-readme.md

# Extending Boundary: adding additional field to an existing API

A very high level list of things to do
when you're adding an additional field to an existing API and corresponding CLI command.

## Add the new field to a repository

Once you've figured out that you need an additional field in Boundary's domain model,
then you need to build in support for your new field from the bottom up starting with a repository's database schema.

* Make schema changes:
  * Define the new column and provide for the migration of existing data
    * Create a new migration under `internal/db/schema/migrations/oss/postgres`

* Add the new field to the storage protobuf

  * storage protobufs are under: `internal/proto/controller/storage`
  * Define a gorm tag for the new field via `@gotags`
    (`@inject_tag` has been deprecated)
  * Define a `custom_options.v1.mask_mapping` for the field
    which maps the storage `this` field to the API `that` field
    (yes, it's the opposite of how it's defined for the API protobuf)
  * Run `make proto` after modifying storage protobuf

* Extend the existing repository function for Updating the resource to incorporate the new field.
  This could/may entail defining new options for the Update function.
* Check the repository's Create function for the resource,
  since you may need to incorporate the new field here as well.

## Add new fields to the API/SDK resource protobufs

Now that the repository supports the new field,
you can move on to adding this new field to Boundary's API layer and the generated SDK.
The first step in the process is to add it to the API/SDK protobufs.

* API protobufs are under: `internal/proto/controller/api/resources`
* Define a `custom_options.v1.mask_mapping` tag for the field
  which maps the API `this` field to the storage `that` field
  (yes, it's the opposite of how it's defined for a storage protobuf)
* Define a `custom_options.v1.generate_sdk_option` tag to change the SDK and add
  API options (DefaultX, WithX functions).
* Define a data classification/filter tag for the field via `@gotags`
  which specifies how sensitive/secret/public data
  will be handled for the API's audit events.
  See the [classification rubric](./classification-rubric.md)
  for guidelines on classification.
  Please write unit tests to verify the audit event is properly "redacted"
  (see the unit tests of `TestAuthMethod_Tags` for [examples][test example]).

* Run `make proto` and `make api` after modifying the API/SDK protobufs

## Update the API handler service

Now that the API protobufs have been updated,
you can move on to adding this new field to the API service handler.

* Service handlers are under: `internal/daemon/controller/handlers`
* Incorporate the new field into the handlers `updateInRepo` func.
  You'll need to incorporate the inbound protobuf's field with the repository's update function.
  This could include adding repository options to the Update function call
  or passing the new field as a parameter to the call.
  This work will be based on how you extended the repository in the previous steps.
* Incorporate the new field into the handler's `ToProto` function.

## Update the CLI's command for updating the resource

At this point, the new field is available via Boundary's API.
All that's left is to incorporate it into Boundary's CLI for the appropriate command.

* CLI commands are under: `internal/cmd/commands`
* Incorporate the new fields to the command's `funcs.go`.
  Just a suggestion here: you may want to define a const for the new field name
  and reuse it everywhere it's required (which is several places)
* Run `make cli` and `make install`, before attempting to test cli changes

[test example]: tests/api/authmethods/classification_test.go

## Additional steps for new API/CLI commands:

* After building out the gRPC service, add the new API service definition to the
  `inputStructs` for API generation: `internal/api/genapi` then run `make api`
  or `make gen` 
* Add the new CLI command definition to the `inputStructs` for CLI generation:
  `internal/cmd/gencli` then run `make cli` or `make gen`
* Add the new `cli.CommandFactory` to the `cmd.initCommands(...)`:
  `internal/cmd` then run `make cli` or `make gen`
* Fill out the required funcs in the command's `func.go` following the same
  suggestion to define consts for field names and reuse them everywhere they are
  required. 
* Run `make cli` and `make install`, before attempting to test cli changes