Schema and generator upgrades (prerequisite for write endpoints) #3

New issue

Open

opened 2026-05-16 10:02:06 +02:00 by heiko · 1 comment

heiko commented

2026-05-16 10:02:06 +02:00

Owner

Plan 6: Schema and generator upgrades (prerequisite for write endpoints)

Goal

Give api.yaml and the generator the knobs needed for the next batch of endpoints,
and fix the generated type name prefix.

6a — Rename generated type prefix (do first, while surface is small)

Generated names like GetTestParams, GetDomainModifyResult embed the HTTP method.
That becomes wrong once POST endpoints exist.

Change: drop the method prefix from generated type names.

GetTestParams → TestParams
GetDomainModifyResult → DomainModifyResult
GetQueryDomainListParams → QueryDomainListParams
etc.

Files: dmapi/api.go.template, then go generate ./....
No logic changes — pure rename.

6b — HTTP method per endpoint

Currently everything is GET. The template hardcodes http.MethodGet.

YAML addition:

- endpoint:
    path: domain-register
    method: Post        # new field, defaults to Get

Generator: already reads Endpoint.Method; the template already has:

http.Method {{- with .Endpoint.Method }} {{- . -}} {{ else -}} Get {{- end -}}

So this is already wired — just start using it in api.yaml.

Audit: check domain-modify, contact-create/modify/delete,
ns-create/modify/delete, domain-register/renew/delete, dns-zone-put,
grants-invite/revoke — all should be POST.

6c — Enum param types

Some params accept only a fixed set of values (e.g. status: production,
privacy: basic|pro). Current values.String accepts anything.

Option A (simple): add validation in YAML:

params:
  status:
    type: string
    enum: [production]
    required: true

Generator emits a Validate() that checks the set. Reuses the existing
required[T] / Validate() pattern.

Option B (skip for now): document the constraint in help: text only.
Simpler, fine for a first pass.

6d — Mutually exclusive param groups

query-whois requires exactly one of domain, contact, host.

YAML addition:

- endpoint:
    path: query-whois
  params:
    domain:
      type: string
      oneof: object
    contact:
      type: string
      oneof: object
    host:
      type: string
      oneof: object

Generator emits a group-level Validate() on the Params struct.
Only needed for query-whois; query-object is deprecated so skip it.

6e — Endpoint aliases

ns-create = host-create, ns-modify = host-modify, ns-delete = host-delete.

YAML addition:

- endpoint:
    path: ns-create
    aliases: [host-create]

Generator registers both names in APICalls pointing to the same *APICall.

# Plan 6: Schema and generator upgrades (prerequisite for write endpoints) ## Goal Give `api.yaml` and the generator the knobs needed for the next batch of endpoints, and fix the generated type name prefix. ## 6a — Rename generated type prefix (do first, while surface is small) Generated names like `GetTestParams`, `GetDomainModifyResult` embed the HTTP method. That becomes wrong once POST endpoints exist. **Change**: drop the method prefix from generated type names. - `GetTestParams` → `TestParams` - `GetDomainModifyResult` → `DomainModifyResult` - `GetQueryDomainListParams` → `QueryDomainListParams` - etc. Files: `dmapi/api.go.template`, then `go generate ./...`. No logic changes — pure rename. ## 6b — HTTP method per endpoint Currently everything is GET. The template hardcodes `http.MethodGet`. **YAML addition**: ```yaml - endpoint: path: domain-register method: Post # new field, defaults to Get ``` **Generator**: already reads `Endpoint.Method`; the template already has: ``` http.Method {{- with .Endpoint.Method }} {{- . -}} {{ else -}} Get {{- end -}} ``` So this is already wired — just start using it in api.yaml. **Audit**: check `domain-modify`, `contact-create/modify/delete`, `ns-create/modify/delete`, `domain-register/renew/delete`, `dns-zone-put`, `grants-invite/revoke` — all should be POST. ## 6c — Enum param types Some params accept only a fixed set of values (e.g. `status: production`, `privacy: basic|pro`). Current `values.String` accepts anything. **Option A (simple)**: add validation in YAML: ```yaml params: status: type: string enum: [production] required: true ``` Generator emits a `Validate()` that checks the set. Reuses the existing `required[T]` / `Validate()` pattern. **Option B (skip for now)**: document the constraint in `help:` text only. Simpler, fine for a first pass. ## 6d — Mutually exclusive param groups `query-whois` requires exactly one of `domain`, `contact`, `host`. **YAML addition**: ```yaml - endpoint: path: query-whois params: domain: type: string oneof: object contact: type: string oneof: object host: type: string oneof: object ``` Generator emits a group-level `Validate()` on the Params struct. Only needed for `query-whois`; `query-object` is deprecated so skip it. ## 6e — Endpoint aliases `ns-create` = `host-create`, `ns-modify` = `host-modify`, `ns-delete` = `host-delete`. **YAML addition**: ```yaml - endpoint: path: ns-create aliases: [host-create] ``` Generator registers both names in `APICalls` pointing to the same `*APICall`.

heiko commented

2026-05-22 11:38:00 +02:00

Author

Owner

AI attribution comment added per repository instruction for this open issue.\n\n(co)authored by ai:gpt-5-codex