Repository navigation
docs: describe the Workspaces API operations and parameters - #31539
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. Part of DOCS-1439. Assisted-by: AI
Part of DOCS-1439. Assisted-by: AI
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.
This describes the 20 Workspaces routes that had no
@Description, fixes parameter text that was wrong or thin on them, and leaves the routes that #30125 documents alone.The reference comes from
swagger.json, whichmake genbuilds from these annotations.Merge notes
This PR doesn't touch #31473's exemption lists.
If #31473 merges first,
TestEndpointsDocumentednames each route on this PR to remove from those lists.GET /api/v2/workspaces/{workspace}/watch-wsis not touched, because #30125 owns it.Its sibling
GET /api/v2/workspaces/{workspace}/watchis described here, and points towatch-wsas its replacement.Existing text I corrected on routes in this list:
include_deletedonGET /api/v2/workspaces/{workspace}said it returns data "instead of HTTP 404". The handler returns410 Gone, so the text now says that. The text on the by-name route stays at404, which is what that handler returns.qonGET /api/v2/workspaceslisted 11 keys.searchquery.Workspacesaccepts more, so the text now lists all of them.usersaid "User ID, name, or me" or "Username, UUID, or me". Both routes resolve it withhttpmw.ExtractUserParamorExtractOrganizationMembersParam, which take an ID, a username, orme, so they now use the shared wording.Verification
A JSON diff of
swagger.jsonagainstmainshows 45 changes, all adding or editingdescriptionvalues on these routes and their parameters, and nothing else.The 17 remaining thin parameters are all
workspacepath IDs, which accept only a UUID, soWorkspace IDis complete.check_routes.pywas run against the fresh list for this branch, which matches the shared list except that it reflects these edits.doc-checkran in author self-check mode on the branch diff, persona by persona.The Fact Checker found two incomplete claims, which the Skeptic confirmed.
The six update routes and the two ACL routes said the workspace owner has the permission outright, but it comes from the Organization Workspace Access role, so the text now names it.
GET .../agent-connection-watchsaidbuild_updateis sent whentransitionorjob_statuschanges, but the server also sends it first and when the build number changes, so the text now says so.The Continuity Editor and the Copy Editor found nothing.
The fixes are in the follow-up commit, and the swagger tests,
check_routes.py, and theswagger.jsondiff were run again.Claims checked against the code
PATCH /api/v2/workspaces/{workspace},/autostart,/ttl,/dormant,/autoupdates,/usagecoderd/database/dbauthz/dbauthz.go:9138,:9300,:9453,:9414,:9287(UpdateWorkspace, autostart, TTL, dormant, automatic updates),coderd/workspaces.go:1848,coderd/rbac/roles.go:236to:244(orgWorkspaceAccessMemberPerms, not part of the member floor),:414(Owner),:587(Organization Admin),docs/admin/users/groups-roles.md:36to:38PATCH /api/v2/workspaces/{workspace}coderd/workspaces.go:1259PUT .../autostartcodersdk/workspaces.go:333to:336,coderd/workspaces.go:1350,:1376,:3251PUT .../ttlnullor0turns autostop off, template can disallow it, prebuilt workspaces failcoderd/workspaces.go:54to:58,:1457,:1472,:3183to:3215PUT .../dormant304when already in that state, prebuilt workspaces fail, owner notified when another user marks it dormantcoderd/workspaces.go:1590,:1600,:1655PUT .../extendcoderd/workspaces.go:59,:1747,:3235:1775,:1781,:1787,:1805POST .../usageworkspace-usageexperiment andagent_idplusapp_namecounts an app sessioncoderd/workspaces.go:1853to:1860,codersdk/deployment.go:5503(ExperimentWorkspaceUsage,"workspace-usage")PUTandDELETE .../favoritecoderd/workspaces.go:1958,:2007PUT .../autoupdatesalwaysornevercoderd/workspaces.go:2074GET .../resolve-autostartparameter_mismatchneeds a template that requires the active version oralwaysupdates, an older build, and an unresolved parametercoderd/workspaces.go:2125,:2140,:2190GET .../watchping,data, anderror, a firstping, then the current workspace on each changecoderd/workspaces.go:2351,codersdk/serversentevents.go:23to:25GET .../timingscoderd/workspaces.go:2469(GetLatestWorkspaceBuildByWorkspaceID),coderd/workspacebuilds.go:1669to:1700GET .../acladminoruserole, minimal identity onlycoderd/workspaces.go:2507to:2601,codersdk/workspaces.go:843to:844PATCHandDELETE .../aclcoderd/database/dbauthz/dbauthz.go:9149,:2845,coderd/workspaces.go:2637,:2652,:2759,:2790to:2805PATCHandDELETE .../aclcoderd/rbac/roles.go:236to:244,:414(Owner),:587(Organization Admin),:1195to:1245(members share only when the organization lets everyone)GET .../agent-connection-watchagent_nameselects the agent, server closes on any client messagecoderd/workspaceconnwatcher/watcher.go:74,:135,:217to:256,:258to:332,codersdk/workspacesdk/workspaceagentconnwatch.go:27to:55GET /api/v2/workspaces/{workspace}410 Gonefor a deleted workspace unlessinclude_deletedistruecoderd/workspaces.go:98GET /api/v2/users/{user}/workspace/{workspacename}404for a deleted workspace unlessinclude_deletedistruecoderd/workspaces.go:331to:345GET /api/v2/workspacesqkeyscoderd/workspaces.go:188to:260(GetWorkspacesauthorizes the query itself),coderd/searchquery/search.go:323to:390GET /api/v2/workspaces,GET .../available-userslimitandoffsetdefault to0coderd/workspaces.go:192,coderd/users.go:386,coderd/pagination.go:19to:23GET .../available-userscoderd/workspaces.go:3341,coderd/rbac/roles.go:414,:587GET .../available-usersquses the user search keyscoderd/workspaces.go:3349,coderd/users.go:374to:410,coderd/searchquery/search.go:217to:231Writing rules applied
dbauthzorAuthorizecalls andcoderd/rbac/roles.go.RequireFeatureMW.watchroute keeps@Deprecatedand names its replacement by full path.workspace-usageexperiment appears by its exact name in backticks.user,organization,limit, andoffset, copied exactly.Part of DOCS-1439.
Generated by Coder Agents on behalf of @nickvigilante.