dcon-api-sync

name	dcon-api-sync
description	Adds or updates dcon CLI support for Diode Console JSON-RPC methods and parameters. Use when console.diode.io/docs/api changes, when adding fleet.* endpoints, updating internal/api/registry.go, fleet subcommands, or syncing dcon with the Console API.

dcon API sync

Update dcon when the Diode Console API gains or changes methods/parameters.

Source of truth: https://console.diode.io/docs/api (not stale copies in this repo).

Full checklist: docs/api-sync.md

Workflow

Copy and track progress:

- [ ] 1. Diff docs vs internal/api/registry.go
- [ ] 2. Update registry + ValidateExtra
- [ ] 3. Update internal/api/registry_test.go
- [ ] 4. Add/update cmd/fleet.go subcommand (if appropriate)
- [ ] 5. Add row to cmd/fleet_test.go (or api test)
- [ ] 6. Update docs/api-sync.md method table if list changed
- [ ] 7. go test ./... && go build .

Step 1 — Registry entry

Edit internal/api/registry.go → var Methods:

Registry field	API docs
Map key	Exact method string (fleet.member.list)
Description	Short summary from docs
Params[].Name	snake_case JSON names (fleet_id)
Params[].Required	Required in API
Params[].Kind	KindString, KindInt, or KindJSON for arrays/objects

Add ValidateExtra when docs specify rules plain Required cannot express:

Pattern	Example methods
Exactly one of A or B	fleet.member.get → member_id xor address
A or B required	fleet.member.add_batch → members or addresses
Alternative shapes	fleet.member.remove_batch → member_ids or fleet_id+addresses

Reuse existing validators (validateMemberGet, etc.) or add validate… in the same file.

Step 2 — Tests (required)

internal/api/registry_test.go

• Happy path with minimal valid params
• Each missing required field
• Each ValidateExtra failure

cmd/fleet_test.go — add to TestFleetCommandsRPCBody:

{
    name:   "descriptive name",
    args:   []string{"fleet", "...", "--fleet-id", "f1", ...},
    method: "fleet.example",
    want:   map[string]any{"fleet_id": "f1", ...},
},

Tests use httptest; call resetCommandFlags(rootCmd) before Execute().

For api-only methods, extend TestAPICommand or add a similar table test.

Step 3 — Fleet subcommand (preferred)

Edit cmd/fleet.go:

1. Cobra command under fleet or fleet member
2. kebab-case flags → snake_case in map[string]any params
3. return runRPC(fleetURL, "<method>", params) — do not duplicate HTTP logic
4. Arrays: --members-json (JSON) or comma-separated --addresses / --member-ids

Skip a subcommand only if params are too complex for flags; document dcon api <method> --params-json '…' in Long help.

Step 4 — Parameter-only changes

If the method name is unchanged:

• Update Params in registry (required/optional/kind)
• Adjust fleet flags and RunE param map
• Update validation tests and fleet_test want map

Conventions

• Do not commit API keys; tests use DCON_API_KEY or temp config
• Unknown methods: dcon api still works without registry entry; known methods must validate
• Default URL: https://console.diode.io/api/v1/rpc in cmd/root.go
• Run go test ./... before finishing

File map

Change	File
Method catalog	internal/api/registry.go
Validation tests	internal/api/registry_test.go
Typed CLI	cmd/fleet.go
RPC body tests	cmd/fleet_test.go
Generic flags	cmd/params.go
Maintainer docs	docs/api-sync.md

Verify

go test ./...
go build -o dcon .
./dcon methods                    # new method listed
./dcon fleet <subcmd> --help      # if subcommand added

Server cross-check (optional)

For ambiguous doc changes, read docs/specs/feature-console-api.md in the console repo.