Repository navigation
docs: describe the template and workspace control API operations - #31520
Closed
nickvigilante wants to merge 2 commits into
Closed
nickvigilante wants to merge 2 commits into
nickvigilante wants to merge 2 commits into
Conversation
The REST API reference renders these routes from swagger.json, and they had no description. This adds descriptions and fuller parameter text for template ACLs, prebuild invalidation, quiet hours, the connection log, workspace sharing settings, and external agent credentials. Part of DOCS-1439. Assisted-by: AI
A doc-check self-review found the connection log limit text described omitted-parameter behavior on a parameter marked required, the `q` search keys without code formatting, and ambiguous wording in the workspace sharing text. Part of DOCS-1439. Assisted-by: AI
This was referenced Oct 29, 2026
Collaborator
Author
|
Combined into #31562, where this PR's changes are the commit Generated by Coder Agents on behalf of @nickvigilante. |
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
Adds
@Descriptiontext to the 10 template and workspace control routes that had none (template ACLs, prebuild invalidation, quiet hours, the connection log, workspace sharing settings, and external agent credentials), and replaces thin or incomplete parameter text on those routes.The REST API reference renders these routes from
swagger.json, so they showed only a title.Merge notes
This PR doesn't touch the exemption lists in #31473.
If #31473 merges first,
TestEndpointsDocumentednames each route on this PR to remove from those lists.GET /api/v2/organizations/{organization}/paginated-groupsalready had a description, but its description had raw braces outside backticks, whichcheck_routes.pyflags.This PR wraps the two paths in backticks and gives them the full
/api/v2prefix, and improves itsorganization,limit,offset, andafter_idparameters.Verification
Head `33f34559fe`, after the self-check commit.
The
swagger.jsondiff againstorigin/mainchanges onlydescriptionvalues (26 changed on the routes in this PR, proven with a JSON walk that fails on any other change).Remaining
THINlines are path IDs that accept only a UUID (templateandworkspace), soTemplate IDandWorkspace IDare complete.Doc-check self-check
Ran the
doc-checkskill in author self-check mode on the branch diff, one persona at a time: Fact Checker, Continuity Editor, Copy Editor, then Skeptic on the survivors.Fixed 3 blocking findings: the
limittext onGET /api/v2/connectionlogno longer says what happens when the parameter is omitted (the annotation marks it required), theqsearch keys are in backticks, and the workspace sharing text no longer has an ambiguousit. Also reworded theservice_accountssentence.Skeptic rejected 1 finding.
Rejected: a Fact Checker note that the template ACL permission sentence leaves out users with the template
adminrole, because the sentence doesn't claim to list every holder.Annotation bugs noticed, not fixed here
GET /api/v2/connectionlog:limitis marked required in the annotation, but the handler treats it as optional (ParsePaginationdefaults it to0, which returns up to100results).GETandPUT /api/v2/users/{user}/quiet-hours:@Successdeclares an array ofcodersdk.UserQuietHoursScheduleResponse, but the handlers return a single object.GETandPATCH .../settings/workspace-sharing:organizationcarriesformat(uuid), but the route accepts an ID, name, ordefault.GETandPUT /api/v2/users/{user}/quiet-hours:usercarriesformat(uuid), but the route accepts an ID, username, orme.Claims checked against the code
GET /api/v2/connectionlogenterprise/coderd/coderd.go:385(RequireFeatureMW(FeatureConnectionLog))GET /api/v2/connectionlogcoderd/database/dbauthz/dbauthz.go:2135,4052,coderd/rbac/roles.go:485,627GET /api/v2/connectionlogcoderd/database/dbauthz/dbauthz.go:2141,4059(prepareSQLFilter)GET /api/v2/connectionlogcoderd/database/queries/connectionlogs.sql:145GET /api/v2/connectionloglimitof0returns up to 100 resultscoderd/database/queries/connectionlogs.sql:151GET /api/v2/connectionlogcountcapped,count_capis 2000enterprise/coderd/connectionlog.go:20GET /api/v2/connectionlogqkeys, enum values,mealiases, andtypeexclusive withmethodandappcoderd/searchquery/search.go:91-151GETandPATCH /api/v2/organizations/{organization}/settings/workspace-sharingorganizationtakes ID, name, ordefaultenterprise/coderd/coderd.go:513-523(ExtractOrganizationParam),coderd/httpmw/organizationparam.go:54-85GET .../workspace-sharing--disable-workspace-sharingforcessharing_globally_disabledandnoneenterprise/coderd/workspacesharing.go:42-50,codersdk/deployment.go:3824-3826PATCH .../workspace-sharingenterprise/coderd/workspacesharing.go:82,coderd/rbac/roles.go:421-432,596-625PATCH .../workspace-sharingnoneorservice_accountsremoves existing sharesenterprise/coderd/workspacesharing.go:173-180PATCH .../workspace-sharingsharing_disabledapplies only whenshareable_workspace_ownersis emptyenterprise/coderd/workspacesharing.go:95-104GETandPATCH /api/v2/templates/{template}/acl,GET .../acl/availableenterprise/coderd/coderd.go:631-637(templateRBACEnabledMW),enterprise/coderd/templates.go:348GET .../acl,GET .../acl/availablecoderd/database/dbauthz/dbauthz.go:9965-9987,enterprise/coderd/templates.go:46PATCH .../aclcoderd/database/dbauthz/dbauthz.go:8651-8657coderd/rbac/roles.go:508-512,679, Owner and Organization Admin viaallPermsExceptatcoderd/rbac/roles.go:421-432,596-625PATCH .../acladminanduse, empty string removes, omitted entries unchangedcodersdk/templates.go:205-236,enterprise/coderd/templates.go:266-277GET .../acl/availableqandlimitenterprise/coderd/templates.go:54-70POST /api/v2/templates/{template}/prebuilds/invalidateenterprise/coderd/coderd.go:643(FeatureWorkspacePrebuilds)POST .../prebuilds/invalidateenterprise/coderd/templates.go:397,coderd/database/dbauthz/dbauthz.go:8502-8509POST .../prebuilds/invalidatecoderd/database/queries/presets.sql:109-120,coderd/prebuilds/global_snapshot.go:127-137,codersdk/templates.go:580-582GETandPUT /api/v2/users/{user}/quiet-hoursenterprise/coderd/users.go:19-37,enterprise/coderd/coderd.go:715-719GET .../quiet-hoursuser_setanduser_can_setenterprise/coderd/schedule/user.go:45-90PUT .../quiet-hours--allow-custom-quiet-hoursenterprise/coderd/users.go:110,enterprise/coderd/schedule/user.go:94-96,codersdk/deployment.go:4020-4026PUT .../quiet-hourscoderd/database/dbauthz/dbauthz.go:8996-9003,coderd/rbac/roles.go:463,539-541PUT .../quiet-hoursCRON_TZ=prefix, example from the defaultcodersdk/users.go:362-372,enterprise/coderd/schedule/user.go:55-68,codersdk/deployment.go:4010-4013userparameter on quiet hoursmeenterprise/coderd/coderd.go:715-720(ExtractUserParamat line 719),coderd/httpmw/userparam.go:34-62GET /api/v2/workspaces/{workspace}/external-agent/{agent}/credentialsenterprise/coderd/coderd.go:761(FeatureWorkspaceExternalAgent)GET .../external-agent/{agent}/credentialsenterprise/coderd/workspaceagents.go:48,coderd/rbac/roles.go:400-425GET .../external-agent/{agent}/credentialsenterprise/coderd/workspaceagents.go:54-103GET /api/v2/organizations/{organization}/paginated-groupsorganizationtakes ID, name, ordefaultenterprise/coderd/coderd.go:564-569,coderd/httpmw/organizationparam.go:54-85GET .../paginated-groupslimitdefault0returns all,offset,after_idkeysetcoderd/pagination.go:14-24,coderd/database/queries/groups.sql:107-130Writing rules applied
dbauthzandroles.go.RequireFeatureMWor an entitlement middleware.userandorganizationwording, only where the route uses the matchinghttpmwextractor.limitdefault (100) instead of the shared wording for the connection log./api/v2paths and backticks around field names, enum values, and flags.Part of DOCS-1439.
Generated by Coder Agents on behalf of @nickvigilante.