Skip to content

docs: describe the groups and workspace quota API operations - #31544

Closed
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-groups
Closed

nickvigilante wants to merge 1 commit into
mainfrom
vigilante/api-descriptions-groups

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

This adds a @Description to the 11 group, group member, and workspace quota routes in the Enterprise tag that had none, and improves the text of their parameters.
The REST API reference renders these routes from swagger.json, so their pages showed only a title.

I also fixed existing parameter text on routes in this list: the group path parameter on PATCH /api/v2/groups/{group} and DELETE /api/v2/groups/{group} said Group name, but the route resolves a group ID with ExtractGroupParam, so it now says Group ID.
The has_member query parameter said User ID or name, and the handler resolves a user ID or username, so it now says that.

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 13-enterprise-groups.txt
summary: need=11 problems=0 thin_params_left=4

$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	1.201s

$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	1.694s

A JSON diff of swagger.json against origin/main shows 11 operation descriptions and 27 parameter descriptions changed, and nothing else.
The four remaining thin parameters are group path IDs that accept only a UUID, so Group ID. is complete.

Claims checked against the code
Route Claim Evidence
Every route under /api/v2/groups and /api/v2/organizations/{organization}/groups Requires a Premium license enterprise/coderd/coderd.go:533-537,650-653 (templateRBACEnabledMW), enterprise/coderd/templates.go:348-367 (RequireFeatureMW(FeatureTemplateRBAC))
Both workspace quota routes No license line; budget is -1 without the template RBAC entitlement enterprise/coderd/coderd.go:520-530,687-694, enterprise/coderd/workspacequota.go:225-242
GET /api/v2/groups, GET /api/v2/organizations/{organization}/groups Returns only the groups you can read coderd/database/dbauthz/dbauthz.go:4370-4380 (fetchWithPostFilter)
GET /api/v2/groups organization is an ID or name, has_member an ID or username, group_ids UUIDs enterprise/coderd/groups.go:714-745
GET /api/v2/organizations/{organization}/groups Same handler as GET /api/v2/groups with organization set enterprise/coderd/groups.go:556-563
Both group read routes and all member routes Members returned only when you can read them coderd/database/dbauthz/dbauthz.go:4342-4348 (fetchWithPostFilter)
GET /api/v2/groups/{group}, GET .../groups/{groupName} Read on the group: members for their own groups, plus the roles named coderd/rbac/roles.go:281-283,489,522,543,630,660,687, coderd/database/dbauthz/dbauthz.go:4323-4329
GET /api/v2/groups/{group} exclude_members omits members; total_member_count is still returned enterprise/coderd/groups.go:436-452, codersdk/groups.go:34-37
PATCH /api/v2/groups/{group} Needs update on the group; Owner, User Admin, Organization Admin, Organization User Admin coderd/database/dbauthz/dbauthz.go:8282-8287, coderd/rbac/roles.go:422,543,587-610,660
PATCH /api/v2/groups/{group} Everyone can't be renamed, given a display name, or have members changed enterprise/coderd/groups.go:137-149,162-167
PATCH /api/v2/groups/{group} Users in add_users and remove_users must be organization members enterprise/coderd/groups.go:170-205
DELETE /api/v2/groups/{group} Needs delete on the group; Everyone can't be deleted coderd/database/dbauthz/dbauthz.go:2464-2466, enterprise/coderd/groups.go:373-378
POST /api/v2/organizations/{organization}/groups Needs create on groups in the organization; the four roles named coderd/database/dbauthz/dbauthz.go:6672-6674, coderd/rbac/roles.go:422,543,587-610,660
POST /api/v2/organizations/{organization}/groups 409 on a duplicate name; Everyone, new, create rejected; 255 characters at most enterprise/coderd/groups.go:58-85, codersdk/name.go:124-137
POST, PATCH groups quota_allowance adds to each member's budget coderd/database/queries/quotas.sql:1-15
Both GET .../members routes q bare term and keys; limit, offset, after_id follow ParsePagination, 0 means no limit coderd/searchquery/search.go:206-232, coderd/pagination.go:14-24, coderd/database/queries/groupmembers.sql (GetGroupMembersByGroupIDPaginated)
Both workspace quota routes Needs read on the user: yourself, or the roles named coderd/database/dbauthz/dbauthz.go:5034-5048, coderd/rbac/roles.go:463,488,521,539,594,650
Both workspace quota routes Budget is the sum of group quota allowances in the organization coderd/database/queries/quotas.sql:1-15, enterprise/coderd/workspacequota.go:225-242
GET /api/v2/workspace-quota/{user} Deprecated, uses the default organization, replacement path enterprise/coderd/workspacequota.go:186-205
organization and user path parameters ID, name, or default; ID, username, or me enterprise/coderd/coderd.go:520-538, coderd/httpmw/organizationparam.go:69-84, coderd/httpmw/userparam.go:36-44
doc-check self-check

Author self-check mode, run on the annotation text in the diff, with nothing posted to GitHub.
Personas that ran: Fact Checker, Consistency, Language, and Skeptic (verifier).
Personas skipped: Cartographer, Newcomer, Reader Advocate, and Architect, because no hand-written docs page or navigation changed, only annotation text and its generated output.
No blocking findings remain.
make lint/emdash passed, and the generated docs/reference/api/enterprise.md went through the markdownlint step of make gen.

Writing rules applied
  • One to three sentences in present tense, active voice, each starting with a verb.
  • "Requires a Premium license." only on routes behind RequireFeatureMW, here through templateRBACEnabledMW, and not on the workspace quota routes.
  • Role display names, and only roles traced through roles.go.
  • Filtering: group and member lists say they return only what you can read.
  • The deprecated route keeps @Deprecated and names the replacement by its full path.
  • Shared wording for the organization, user, limit, offset, and after_id parameters where the handler matches it.
  • Body parameters say what the body is.
  • Literals, field names, and enum values in backticks, with full API paths.
  • No em dashes, en dashes, semicolons in prose, or raw angle brackets and braces outside backticks.
CI flakes unrelated to this change

test-go-pg-17 failed in coderd/x/chatd TestChatTurnStopsAtStepLimit/Default, a package this PR doesn't touch: https://github.com/coder/coder/actions/runs/40930616886/job/123647935215

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 describes the group and group member routes and the workspace quota
routes, improves their parameter text, and corrects the group path
parameter on the update and delete routes, which takes a group ID and
not a name.

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 groups and workspace quota API operations. 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