Skip to content

docs: describe the Applications API operations and parameters - #31522

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-applications
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-applications

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes the two Applications API routes and improves the redirect_uri parameter, so the REST API reference page for each route has more than a title.
The reference renders from swagger.json, and these routes had no description.

Merge notes

This PR doesn't touch #31473's exemption lists.
If #31473 merges first, TestEndpointsDocumented names each route on this PR to remove from those lists.

Verification

$ python3 check_routes.py <route list>
summary: need=2 problems=0 thin_params_left=0
$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
$ make lint/emdash
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.694s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	1.809s
OK: no emdash or endash characters found.

A JSON diff of swagger.json against origin/main changes only description values: 3 in total, all on routes in this PR or their parameters, and no other value differs.

doc-check self-check

Ran the doc-check skill in author self-check mode on the branch diff, one persona at a time: Fact Checker, Continuity Editor, Copy Editor, then Skeptic on what survived. The other personas (Cartographer, Newcomer, Reader Advocate, Architect) didn't run.

  • Fixed, Continuity Editor: the redirect_uri text said Required while the same row shows Required: false. The text now says what the route does without the word (the annotation bug is listed below).
  • Copy Editor and Fact Checker returned no other blocking findings, and Skeptic rejected 0.
Claims checked against the code
Route Claim Evidence
GET /api/v2/applications/host Returns the wildcard hostname for subdomain apps, empty when the deployment sets none coderd/workspaceapps.go:39, coderd/workspaceapps/appurl/appurl.go:43-46
GET /api/v2/applications/host Deprecated in favor of /api/v2/regions and the primary workspace proxy's wildcard_hostname coderd/workspaceapps.go (@Deprecated annotation), codersdk/workspaceproxy.go:197-201
GET /api/v2/applications/auth-redirect Redirects to the login page when you aren't signed in coderd/coderd.go:1965 (apiKeyMiddlewareRedirect), coderd/coderd.go:1119-1122 (RedirectToLogin: true)
GET /api/v2/applications/auth-redirect The key has the application_connect scope and expires with your session or after the default session duration, whichever comes first coderd/workspaceapps.go:112-122
GET /api/v2/applications/auth-redirect Adds the encrypted key to the redirect_uri query and redirects coderd/workspaceapps.go:147-154
redirect_uri query parameter The route returns 400 when it's missing, and it must be the primary wildcard app hostname, a workspace proxy access URL, or a workspace proxy wildcard app hostname coderd/workspaceapps.go:71-74, :86-100
Writing rules applied
  • One to three sentences per route, present tense, first sentence starts with a verb and stands alone on the endpoint card.
  • Permissions name the built-in roles, traced through api.Authorize calls, middleware, and coderd/rbac/roles.go.
  • Routes without a session token say so, and routes with another credential name it.
  • Streams say that the route upgrades to a WebSocket or sends server-sent events, and what each message carries.
  • Full API paths and literals (fields, parameters, values) are in backticks.
  • Shared parameter wording is copied exactly only where the code matches it.
  • No em dashes, en dashes, semicolons, or raw angle brackets and braces outside backticks.
Annotation bugs noticed, not changed here
  • GET /api/v2/applications/auth-redirect documents 307, but the handler redirects with 303 (http.StatusSeeOther, coderd/workspaceapps.go:154).
  • redirect_uri is marked optional, but the handler returns 400 without it.

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

The REST API reference renders these routes from swagger.json, and they
had no description. This adds one to each Applications route and improves the
parameter descriptions.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Applications API operations and parameters. The claims table above still covers that commit.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant