Repository navigation
docs: describe the Templates API operations and parameters - #31540
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 also replaces the thin or inaccurate parameter text on the same routes. Part of DOCS-1439. Assisted-by: AI
The dry-run cancel route also needs permission to update the template, and the unlicensed port sharing check only rejects levels other than public. 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 35 published Templates routes that had none, and replaces thin or wrong parameter text on the same routes (33 parameters).The REST API reference renders these pages from
swagger.json, so they showed only a title.The previous template version route (
.../versions/{templateversionname}/previous) belongs to #30125 and isn't touched.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.Two existing parameter texts were wrong and are fixed here:
GET /api/v2/templateversions/{templateversion}/dry-run/{jobID}/logs,aftersaid "After Unix timestamp", but the handler compares it with the logid(GetProvisionerLogsAfterID), as it does on the template version logs route.beforeis documented but the handler never reads it, so its text now says so.Verification
A JSON diff of
swagger.jsonagainstorigin/mainshows 68 changeddescriptionvalues (35 new route descriptions and 33 parameter descriptions) and no other difference.The 29 remaining thin parameters are all path IDs that accept only a UUID (
templateandtemplateversion), whereTemplate IDandTemplate version IDare complete.The
doc-checkself-check ran persona by persona: Fact Checker, Continuity Editor, Copy Editor, then Skeptic.The Fact Checker found two issues, which the follow-up commit fixes: the dry-run cancel route also needs permission to update the template (
dbauthz.go:8595-8610), and the unlicensedmax_port_share_levelcheck rejects only values other thanpublic.The Fact Checker also confirmed that without a Premium license the
PATCHhandler ignores theupdate_workspace_last_used_atandupdate_workspace_dormant_atfields, because only the enterprise schedule store reads them (enterprise/coderd/schedule/template.go:107-195).The Continuity Editor and Copy Editor reported no findings.
The Skeptic verified both findings and rejected 2 candidate findings that weren't caused by this change.
The checks above were re-run after the follow-up commit.
Claims checked against the code
Line numbers are on this branch.
roles.gorows cite the role definitions: Owner:414, Template Admin:507, Organization Admin:587, Organization Template Admin:669, Auditor:479, Organization Auditor:617, Organization Workspace Access:738.POST /api/v2/organizations/{organization}/templatesdbauthz.go:6873(InsertTemplate),roles.go:414,507,587,669templates.go:280,290,codersdk/organizations.go:158-164userole unlessdisable_everyone_group_accessistruetemplates.go:437-440,db2sdk.go:995require_active_versionsettings are ignoredtemplates.go:471,484,coderd/schedule/template.go:183-190,227,dbauthz/accesscontrol.go:35-68,enterprise/coderd/coderd.go:1069,1167max_port_share_levelreturns a validation errortemplates.go:381,coderd/portsharing/portsharing.go:23,enterprise/coderd/coderd.go:1190PATCH /api/v2/templates/{template}templates_meta_update.go:83-113,templates.go:712dbauthz.go:8679(UpdateTemplateMetaByID),roles.go:414,507,587,669autostop_requirement,autostart_requirement,allow_user_autostart,allow_user_autostop,failure_ttl_ms,time_til_dormant_ms,time_til_dormant_autodelete_ms,update_workspace_last_used_at, andupdate_workspace_dormant_atare ignoredtemplates.go:839,coderd/schedule/template.go:183-190,227(AGPL store keeps stored values),enterprise/coderd/schedule/template.go:107-195(only the enterprise store applies them),enterprise/coderd/coderd.go:1069(FeatureAdvancedTemplateScheduling)require_active_versionand a non-emptydeprecation_messageare ignoredtemplates.go:811,dbauthz/accesscontrol.go:35-68,enterprise/coderd/coderd.go:1167(FeatureAccessControl)max_port_share_levelto anything other thanpublicreturns a validation error (the check is skipped when the value equals the unlicensedpubliclevel)templates.go:755-762,coderd/portsharing/portsharing.go:23,enterprise/coderd/coderd.go:1190(FeatureControlSharedPorts)DELETE /api/v2/templates/{template}templates.go:100-111dbauthz.go:1540(SoftDeleteTemplateByID),roles.go:414,507,587,669GET /api/v2/templates/{template}404if the template is deleted or unreadablehttpmw/templateparam.go:34-37,dbauthz.go:5159GET /api/v2/templates/{template}/daustz_offsetquery parameter with default0insights.go:52,62,67-68dbauthz.go:1590,5174,roles.go:414,479,507,587,617,669,policy.go:17GET /api/v2/organizations/{organization}/templates/{templatename}and the version lookups by namequeries/templates.sql:118GET /api/v2/templates/{template}/versions/{templateversionname}and the organization variantmatched_provisionerswhile the import job is pending, and names are unique per templatetemplateversions.go:1039,1125,templateversions.go:1813GET /api/v2/templateversions/{templateversion}matched_provisionerswhile the import job is pendingtemplateversions.go:76-86GET /api/v2/templates/{template}/versionsinclude_archivedistrue(defaultfalse)queries/templateversions.sql:37,templateversions.go:890,925limit,offset,after_iduse the shared pagination wordingtemplateversions.go:883,coderd/pagination.go:17-22PATCH /api/v2/templates/{template}/versionstemplateversions.go:1472,1486,1493dbauthz.go:8667(UpdateTemplateActiveVersionByID),roles.go:414,507,587,669POST /api/v2/templates/{template}/versions/archiveallarchives every unused version, unused means not in a workspace's latest build and not the active versiontemplateversions.go:1286,queries/templateversions.sql:155-212dbauthz.go:1898(ArchiveUnusedTemplateVersions),roles.go:414,507,587,669POST /api/v2/templateversions/{templateversion}/archivetemplateversions.go:1396,queries/templateversions.sql:155-212POST /api/v2/templateversions/{templateversion}/archiveand.../unarchivedbauthz.go:1898,7798,roles.go:414,507,587,669PATCH /api/v2/templateversions/{templateversion}nameormessagekeeps its valuetemplateversions.go:141-147,186dbauthz.go:8693(UpdateTemplateVersionByID),roles.go:414,507,587,669PATCH /api/v2/templateversions/{templateversion}/canceltemplateversions.go:254,260dbauthz.go:8553(UpdateProvisionerJobWithCancelByID),roles.go:414,507,587,669POST /api/v2/organizations/{organization}/templateversionsfile_idorexample_id, not bothtemplateversions.go:1586dbauthz.go:6881(InsertTemplateVersion),roles.go:414,507,587,669POST /api/v2/templateversions/{templateversion}/dry-runprovisionerd/runner/runner.go:756-830425until the template version's import job has finishedtemplateversions.go:553templateversions.go:533,roles.go:242,414,587,738GET .../dry-run/{jobID}403if the job isn't a dry run of this template versiontemplateversions.go:835,857GET .../dry-run/{jobID}/resources400until the job completesprovisionerjobs.go:215PATCH .../dry-run/{jobID}/cancel400if already completed or canceledtemplateversions.go:765,771templateversions.go:758,dbauthz.go:8595-8610,roles.go:414,587GET .../dry-run/{jobID}/logsandGET /api/v2/templateversions/{templateversion}/logsfollowupgrades to a WebSocket sending one JSON log per message and closes when the job ends; presence of the parameter enables itprovisionerjobs.go:158,593,621,643afteris a log ID;beforeis never readprovisionerjobs.go:184-203,454,694GET /api/v2/templateversions/{templateversion}/dynamic-parametersid-1and is computed with no inputsparameters.go:164-181id; an omittedowner_idkeeps the previous owner;user_idquery sets the starting ownerparameters.go:48-60,193-217parameters.go:141POST .../dynamic-parameters/evaluate425until the import job has finishedparameters.go:102GET .../external-authuser_idfor another user needs permission to create workspaces for that usertemplateversions.go:372GET .../rich-parameters425until the import job has completedtemplateversions.go:312GET .../variables403until the import job has completed, and sensitivevalueanddefault_valueare*redacted*templateversions.go:493,2088-2098GET .../resources400until the import job has completed, and the resources aren't tied to a workspaceprovisionerjobs.go:215,templateversions.go:1980-1986GET .../presetspresets.go:58GET .../parametersandGET .../schemarich-parametersdeprecated.go:22,36,coderd.go:1660GET /api/v2/organizations/{organization}/templates/examples/api/v2/templates/examplestemplates.go:956Writing rules applied
@Descriptionline, with no semicolons, em dashes, or en dashes.dbauthzandroles.go.organization,limit,offset, andafter_id.Part of DOCS-1439.
Generated by Coder Agents on behalf of @nickvigilante.