docs: DEVEX-967 design proposal — API explorer command hyperlinks + pagination - #172
Open
jpage-godaddy wants to merge 1 commit into
Open
docs: DEVEX-967 design proposal — API explorer command hyperlinks + pagination#172jpage-godaddy wants to merge 1 commit into
jpage-godaddy wants to merge 1 commit into
Conversation
… handling [DEVEX-967] Replaces the reverted truncate-to-temp-file prototype from DEVEX-702 with a design based on next_actions, new parameter/response/schema entity commands, and command-driven pagination.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a design proposal document for DEVEX-967 describing how the Rust gddy CLI’s API explorer should replace temp-file truncation with a CLI-native next_actions hyperlink convention, and outlining related command/identifier/pagination changes.
Changes:
- Document a shared
Summary<T>truncation envelope ingddyand a consistent rule for truncation-driven navigation vianext_actions. - Propose new API explorer drill-down commands (
api parameter|response|schema ...) and renamingapi describe/api endpointtoapi operation .... - Propose opt-in, command-driven pagination via a
cli-engine.with_pagination(...)builder (defaults + max limit behavior).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Operation | `getUser` (operationId) or path fragment | already stable today | | ||
| | Parameter | `limit` | not globally unique — scoped by the `--operation` flag on the command, not baked into the id itself. The request body folds in here too, as `in: "body"` (see below). | | ||
| | Response | `200` | same scoping rule: id is just the status code, `--operation` supplies the rest | | ||
| | Operation | `getUser` (operationId) | `--operation <id>` alone is enough — no `--domain` needed. `find_endpoint_exact` (`rust/src/api_explorer/mod.rs:275-294`) already resolves operations catalog-wide today, matching only by `operationId`/path (ambiguity is handled via `--method`, never domain), so `describe`/`call`/`parameter`/`response` all share the same assumption: operationId is globally unique. Nothing enforces that at generation time — `generate-api-catalog` only dedupes domain names (`main.rs:227-229`) — so this is a pre-existing gap this design inherits rather than introduces, worth a separate follow-up if it's ever hit in practice. | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design proposal for DEVEX-967: replaces the truncate-to-temp-file prototype (reverted during DEVEX-702) with a CLI-native "hyperlink" convention — truncated output points at a follow-up command via
next_actionsinstead of a file on disk.Highlights:
Summary<T>truncation envelope living ingddy(notcli-engine), with a fixed rule for what a truncated section links to: standalone list command for 1:many, standalone get command for 1:1/many:1 — never "page 2 of the embedded copy."parameter/response/schemacommands with per-entity identifier rules (short operation-scoped names for parameter/response, request body folded in asin: "body"; dotted-path or$ref-name ids for schema, which is the one atomic/terminal, never-truncated entity).api describe→api operation getandapi endpoint list→api operation list, sinceEndpointis already structured as one method+path+operationId row (an OpenAPI operation, not a path grouping)..with_pagination(...)builder forcli-engineso--limit/--offsetare opt-in per command (not shown in--helpfor commands that ignore them) with a command-level default page size — this requires acli-enginerelease + version bump beforegddycan use it.Nothing here is implemented yet — this is purely the design doc, meant to get stakeholder input before work starts. See the doc's "Open questions" section for the forks still unresolved (deprecation vs. clean break for the rename,
max_limitoverflow behavior, etc).Test plan
N/A — documentation only, no code changes.