From d9436fab69203740a25c29f2d27146bb04bc14c3 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Wed, 11 Jan 2023 16:05:42 +0100 Subject: [PATCH] docs: API enterprise (#5625) * docs: audit, deploymentconfig, files, parameters * Swagger comments in workspacebuilds.go * structs in workspacebuilds.go * workspaceagents: instance identity * workspaceagents.go in progress * workspaceagents.go in progress * Agents * workspacebuilds.go * /workspaces * templates.go, templateversions.go * templateversion.go in progress * cancel * templateversions * wip * Merge * x-apidocgen * NullTime hack not needed anymore * Fix: x-apidocgen * Members * Fixes * Fix * WIP * WIP * Users * Logout * User profile * Status suspend activate * User roles * User tokens * Keys * SSH key * All * Typo * Fix * Entitlements * Groups * SCIM * Fix * Fix * Clean templates * Sort API pages * Fix: HashedSecret * General is first --- Makefile | 2 +- coderd/apidoc/docs.go | 1073 ++++++++++++++++- coderd/apidoc/swagger.json | 974 ++++++++++++++- codersdk/apikey.go | 4 +- codersdk/groups.go | 4 +- codersdk/licenses.go | 4 +- codersdk/provisionerdaemons.go | 6 +- codersdk/replicas.go | 8 +- codersdk/templates.go | 4 +- docs/api/builds.md | 280 ++--- docs/api/enterprise.md | 980 +++++++++++++++ docs/api/organizations.md | 49 + docs/api/schemas.md | 449 ++++++- docs/api/templates.md | 377 +++--- docs/api/users.md | 24 +- docs/manifest.json | 72 +- enterprise/coderd/appearance.go | 15 + enterprise/coderd/coderd.go | 9 +- enterprise/coderd/groups.go | 38 + enterprise/coderd/licenses.go | 24 + enterprise/coderd/provisionerdaemons.go | 17 + enterprise/coderd/replicas.go | 8 + enterprise/coderd/scim.go | 42 +- enterprise/coderd/scim_test.go | 2 +- enterprise/coderd/templates.go | 17 + enterprise/coderd/workspacequota.go | 8 + scripts/apidocgen/generate.sh | 2 +- scripts/apidocgen/markdown-template/debug.def | 1 - scripts/apidocgen/markdown-template/main.dot | 6 +- .../apidocgen/markdown-template/responses.def | 2 +- scripts/apidocgen/postprocess/main.go | 13 + 31 files changed, 4139 insertions(+), 375 deletions(-) create mode 100644 docs/api/enterprise.md delete mode 100644 scripts/apidocgen/markdown-template/debug.def diff --git a/Makefile b/Makefile index 40a981afd5..cd7c316a4e 100644 --- a/Makefile +++ b/Makefile @@ -483,7 +483,7 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me cd site yarn run format:write:only ../docs/admin/prometheus.md -coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen -not \( -path './scripts/apidocgen/node_modules' -prune \) -type f) $(wildcard coderd/*.go) $(wildcard codersdk/*.go) .swaggo +coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen -not \( -path './scripts/apidocgen/node_modules' -prune \) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) .swaggo ./scripts/apidocgen/generate.sh cd site yarn run format:write:only ../docs/api ../docs/manifest.json ../coderd/apidoc/swagger.json diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 17fac114fc..c103fa9ca0 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -45,6 +45,65 @@ const docTemplate = `{ } } }, + "/appearance": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get appearance", + "operationId": "get-appearance", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + }, + "put": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Update appearance", + "operationId": "update-appearance", + "parameters": [ + { + "description": "Update appearance request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + } + }, "/applications/auth-redirect": { "get": { "security": [ @@ -303,6 +362,31 @@ const docTemplate = `{ } } }, + "/entitlements": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get entitlements", + "operationId": "get-entitlements", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Entitlements" + } + } + } + } + }, "/files": { "post": { "security": [ @@ -378,6 +462,172 @@ const docTemplate = `{ } } }, + "/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get groups", + "operationId": "get-groups", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + } + }, + "/groups/{groupName}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get group by name", + "operationId": "get-group-by-name", + "parameters": [ + { + "type": "string", + "description": "Group name", + "name": "groupName", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "/license/{id}": { + "delete": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Delete license", + "operationId": "delete-license", + "parameters": [ + { + "type": "string", + "format": "number", + "description": "License ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + }, + "/licenses": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get licenses", + "operationId": "get-licenses", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Organizations" + ], + "summary": "Add new license", + "operationId": "add-new-license", + "parameters": [ + { + "description": "Add license request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AddLicenseRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, "/organizations": { "post": { "security": [ @@ -449,6 +699,88 @@ const docTemplate = `{ } } }, + "/organizations/{organization}/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get groups by organization", + "operationId": "get-groups-by-organization", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Templates" + ], + "summary": "Create group for organization", + "operationId": "create-group-for-organization", + "parameters": [ + { + "description": "Create group request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateGroupRequest" + } + }, + { + "type": "string", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, "/organizations/{organization}/members/roles": { "get": { "security": [ @@ -582,6 +914,76 @@ const docTemplate = `{ } } }, + "/organizations/{organization}/provisionerdaemons": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get provisioner daemons", + "operationId": "get-provisioner-daemons", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ProvisionerDaemon" + } + } + } + } + } + }, + "/organizations/{organization}/provisionerdaemons/serve": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Serve provisioner daemon", + "operationId": "serve-provisioner-daemon", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "101": { + "description": "Switching Protocols" + } + } + } + }, "/organizations/{organization}/templates": { "get": { "security": [ @@ -1036,6 +1438,144 @@ const docTemplate = `{ } } }, + "/replicas": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get active replicas", + "operationId": "get-active-replicas", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Replica" + } + } + } + } + } + }, + "/scim/v2/Users": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "SCIM 2.0: Create new user", + "operationId": "scim-create-new-user", + "parameters": [ + { + "description": "New user", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + } + } + }, + "/scim/v2/Users/{id}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/scim+json" + ], + "tags": [ + "Enterprise" + ], + "summary": "SCIM 2.0: Get user by ID", + "operationId": "scim-get-user-by-id", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "404": { + "description": "Not Found" + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/scim+json" + ], + "tags": [ + "Enterprise" + ], + "summary": "SCIM 2.0: Update user account", + "operationId": "scim-update-user-status", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update user request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.User" + } + } + } + } + }, "/templates/{id}": { "get": { "security": [ @@ -1319,6 +1859,86 @@ const docTemplate = `{ } } }, + "/templates/{template}/acl": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get template ACLs", + "operationId": "get-template-acls", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.TemplateUser" + } + } + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Update template ACL", + "operationId": "update-template-acl", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + }, + { + "description": "Update template request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateTemplateACL" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, "/templateversions/{templateversion}": { "get": { "security": [ @@ -2852,6 +3472,40 @@ const docTemplate = `{ } } }, + "/workspace-quota/{user}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": [ + "application/json" + ], + "tags": [ + "Enterprise" + ], + "summary": "Get workspace quota by user", + "operationId": "get-workspace-quota-by-user", + "parameters": [ + { + "type": "string", + "description": "User ID, name, or me", + "name": "user", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.WorkspaceQuota" + } + } + } + } + }, "/workspaceagents/aws-instance-identity": { "post": { "security": [ @@ -3819,6 +4473,70 @@ const docTemplate = `{ } }, "definitions": { + "coderd.SCIMUser": { + "type": "object", + "properties": { + "active": { + "type": "boolean" + }, + "emails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "display": { + "type": "string" + }, + "primary": { + "type": "boolean" + }, + "type": { + "type": "string" + }, + "value": { + "type": "string", + "format": "email" + } + } + } + }, + "groups": { + "type": "array", + "items": {} + }, + "id": { + "type": "string" + }, + "meta": { + "type": "object", + "properties": { + "resourceType": { + "type": "string" + } + } + }, + "name": { + "type": "object", + "properties": { + "familyName": { + "type": "string" + }, + "givenName": { + "type": "string" + } + } + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + }, + "userName": { + "type": "string" + } + } + }, "coderd.cspViolation": { "type": "object", "properties": { @@ -3889,7 +4607,6 @@ const docTemplate = `{ "format": "date-time" }, "user_id": { - "description": "NOTE: do not ever return the HashedSecret", "type": "string", "format": "uuid" } @@ -3921,6 +4638,17 @@ const docTemplate = `{ } } }, + "codersdk.AddLicenseRequest": { + "type": "object", + "required": [ + "license" + ], + "properties": { + "license": { + "type": "string" + } + } + }, "codersdk.AgentGitSSHKey": { "type": "object", "properties": { @@ -3973,6 +4701,17 @@ const docTemplate = `{ } } }, + "codersdk.AppearanceConfig": { + "type": "object", + "properties": { + "logo_url": { + "type": "string" + }, + "service_banner": { + "$ref": "#/definitions/codersdk.ServiceBannerConfig" + } + } + }, "codersdk.AssignableRoles": { "type": "object", "properties": { @@ -4250,6 +4989,20 @@ const docTemplate = `{ } } }, + "codersdk.CreateGroupRequest": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "name": { + "type": "string" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.CreateOrganizationRequest": { "type": "object", "required": [ @@ -4875,6 +5628,68 @@ const docTemplate = `{ } } }, + "codersdk.Entitlement": { + "type": "string", + "enum": [ + "entitled", + "grace_period", + "not_entitled" + ], + "x-enum-varnames": [ + "EntitlementEntitled", + "EntitlementGracePeriod", + "EntitlementNotEntitled" + ] + }, + "codersdk.Entitlements": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "string" + } + }, + "experimental": { + "type": "boolean" + }, + "features": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.Feature" + } + }, + "has_license": { + "type": "boolean" + }, + "trial": { + "type": "boolean" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "codersdk.Feature": { + "type": "object", + "properties": { + "actual": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "entitlement": { + "$ref": "#/definitions/codersdk.Entitlement" + }, + "limit": { + "type": "integer" + } + } + }, "codersdk.GenerateAPIKeyResponse": { "type": "object", "properties": { @@ -4972,6 +5787,34 @@ const docTemplate = `{ } } }, + "codersdk.Group": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.User" + } + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.Healthcheck": { "type": "object", "properties": { @@ -4989,6 +5832,27 @@ const docTemplate = `{ } } }, + "codersdk.License": { + "type": "object", + "properties": { + "claims": { + "description": "Claims are the JWT claims asserted by the license. Here we use\na generic string map to ensure that all data from the server is\nparsed verbatim, not just the fields this version of Coder\nunderstands.", + "type": "object", + "additionalProperties": true + }, + "id": { + "type": "integer" + }, + "uploaded_at": { + "type": "string", + "format": "date-time" + }, + "uuid": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.LogLevel": { "type": "string", "enum": [ @@ -5412,6 +6276,42 @@ const docTemplate = `{ } } }, + "codersdk.ProvisionerDaemon": { + "type": "object", + "properties": { + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "provisioners": { + "type": "array", + "items": { + "type": "string" + } + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "updated_at": { + "format": "date-time", + "allOf": [ + { + "$ref": "#/definitions/sql.NullTime" + } + ] + } + } + }, "codersdk.ProvisionerJob": { "type": "object", "properties": { @@ -5545,6 +6445,41 @@ const docTemplate = `{ } } }, + "codersdk.Replica": { + "type": "object", + "properties": { + "created_at": { + "description": "CreatedAt is the timestamp when the replica was first seen.", + "type": "string", + "format": "date-time" + }, + "database_latency": { + "description": "DatabaseLatency is the latency in microseconds to the database.", + "type": "integer" + }, + "error": { + "description": "Error is the replica error.", + "type": "string" + }, + "hostname": { + "description": "Hostname is the hostname of the replica.", + "type": "string" + }, + "id": { + "description": "ID is the unique identifier for the replica.", + "type": "string", + "format": "uuid" + }, + "region_id": { + "description": "RegionID is the region of the replica.", + "type": "integer" + }, + "relay_address": { + "description": "RelayAddress is the accessible address to relay DERP connections.", + "type": "string" + } + } + }, "codersdk.ResourceType": { "type": "string", "enum": [ @@ -5601,6 +6536,20 @@ const docTemplate = `{ } } }, + "codersdk.ServiceBannerConfig": { + "type": "object", + "properties": { + "background_color": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + }, "codersdk.SwaggerConfig": { "type": "object", "properties": { @@ -5771,6 +6720,88 @@ const docTemplate = `{ } } }, + "codersdk.TemplateRole": { + "type": "string", + "enum": [ + "admin", + "use", + "" + ], + "x-enum-varnames": [ + "TemplateRoleAdmin", + "TemplateRoleUse", + "TemplateRoleDeleted" + ] + }, + "codersdk.TemplateUser": { + "type": "object", + "required": [ + "created_at", + "email", + "id", + "username" + ], + "properties": { + "avatar_url": { + "type": "string", + "format": "uri" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "email": { + "type": "string", + "format": "email" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "last_seen_at": { + "type": "string", + "format": "date-time" + }, + "organization_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "role": { + "enum": [ + "admin", + "use" + ], + "allOf": [ + { + "$ref": "#/definitions/codersdk.TemplateRole" + } + ] + }, + "roles": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Role" + } + }, + "status": { + "enum": [ + "active", + "suspended" + ], + "allOf": [ + { + "$ref": "#/definitions/codersdk.UserStatus" + } + ] + }, + "username": { + "type": "string" + } + } + }, "codersdk.TemplateVersion": { "type": "object", "properties": { @@ -5875,6 +6906,23 @@ const docTemplate = `{ } } }, + "codersdk.UpdateTemplateACL": { + "type": "object", + "properties": { + "group_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + }, + "user_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + } + } + }, "codersdk.UpdateUserPasswordRequest": { "type": "object", "required": [ @@ -6435,6 +7483,17 @@ const docTemplate = `{ } } }, + "codersdk.WorkspaceQuota": { + "type": "object", + "properties": { + "budget": { + "type": "integer" + }, + "credits_consumed": { + "type": "integer" + } + } + }, "codersdk.WorkspaceResource": { "type": "object", "properties": { @@ -6634,6 +7693,18 @@ const docTemplate = `{ } } }, + "sql.NullTime": { + "type": "object", + "properties": { + "time": { + "type": "string" + }, + "valid": { + "description": "Valid is true if Time is not NULL", + "type": "boolean" + } + } + }, "tailcfg.DERPMap": { "type": "object", "properties": { diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 1e823c2ef1..ae8733e3a4 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -33,6 +33,57 @@ } } }, + "/appearance": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get appearance", + "operationId": "get-appearance", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + }, + "put": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Update appearance", + "operationId": "update-appearance", + "parameters": [ + { + "description": "Update appearance request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.AppearanceConfig" + } + } + } + } + }, "/applications/auth-redirect": { "get": { "security": [ @@ -257,6 +308,27 @@ } } }, + "/entitlements": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get entitlements", + "operationId": "get-entitlements", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Entitlements" + } + } + } + } + }, "/files": { "post": { "security": [ @@ -324,6 +396,152 @@ } } }, + "/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get groups", + "operationId": "get-groups", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + } + }, + "/groups/{groupName}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get group by name", + "operationId": "get-group-by-name", + "parameters": [ + { + "type": "string", + "description": "Group name", + "name": "groupName", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "/license/{id}": { + "delete": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Delete license", + "operationId": "delete-license", + "parameters": [ + { + "type": "string", + "format": "number", + "description": "License ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK" + } + } + } + }, + "/licenses": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get licenses", + "operationId": "get-licenses", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Organizations"], + "summary": "Add new license", + "operationId": "add-new-license", + "parameters": [ + { + "description": "Add license request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.AddLicenseRequest" + } + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.License" + } + } + } + } + }, "/organizations": { "post": { "security": [ @@ -387,6 +605,78 @@ } } }, + "/organizations/{organization}/groups": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get groups by organization", + "operationId": "get-groups-by-organization", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "tags": ["Templates"], + "summary": "Create group for organization", + "operationId": "create-group-for-organization", + "parameters": [ + { + "description": "Create group request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.CreateGroupRequest" + } + }, + { + "type": "string", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Created", + "schema": { + "$ref": "#/definitions/codersdk.Group" + } + } + } + } + }, "/organizations/{organization}/members/roles": { "get": { "security": [ @@ -506,6 +796,68 @@ } } }, + "/organizations/{organization}/provisionerdaemons": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get provisioner daemons", + "operationId": "get-provisioner-daemons", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.ProvisionerDaemon" + } + } + } + } + } + }, + "/organizations/{organization}/provisionerdaemons/serve": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Serve provisioner daemon", + "operationId": "serve-provisioner-daemon", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Organization ID", + "name": "organization", + "in": "path", + "required": true + } + ], + "responses": { + "101": { + "description": "Switching Protocols" + } + } + } + }, "/organizations/{organization}/templates": { "get": { "security": [ @@ -902,6 +1254,128 @@ } } }, + "/replicas": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get active replicas", + "operationId": "get-active-replicas", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Replica" + } + } + } + } + } + }, + "/scim/v2/Users": { + "post": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "SCIM 2.0: Create new user", + "operationId": "scim-create-new-user", + "parameters": [ + { + "description": "New user", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + } + } + }, + "/scim/v2/Users/{id}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/scim+json"], + "tags": ["Enterprise"], + "summary": "SCIM 2.0: Get user by ID", + "operationId": "scim-get-user-by-id", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "404": { + "description": "Not Found" + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/scim+json"], + "tags": ["Enterprise"], + "summary": "SCIM 2.0: Update user account", + "operationId": "scim-update-user-status", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "User ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Update user request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/coderd.SCIMUser" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.User" + } + } + } + } + }, "/templates/{id}": { "get": { "security": [ @@ -1155,6 +1629,78 @@ } } }, + "/templates/{template}/acl": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get template ACLs", + "operationId": "get-template-acls", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.TemplateUser" + } + } + } + } + }, + "patch": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Update template ACL", + "operationId": "update-template-acl", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Template ID", + "name": "template", + "in": "path", + "required": true + }, + { + "description": "Update template request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateTemplateACL" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.Response" + } + } + } + } + }, "/templateversions/{templateversion}": { "get": { "security": [ @@ -2514,6 +3060,36 @@ } } }, + "/workspace-quota/{user}": { + "get": { + "security": [ + { + "CoderSessionToken": [] + } + ], + "produces": ["application/json"], + "tags": ["Enterprise"], + "summary": "Get workspace quota by user", + "operationId": "get-workspace-quota-by-user", + "parameters": [ + { + "type": "string", + "description": "User ID, name, or me", + "name": "user", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/codersdk.WorkspaceQuota" + } + } + } + } + }, "/workspaceagents/aws-instance-identity": { "post": { "security": [ @@ -3366,6 +3942,70 @@ } }, "definitions": { + "coderd.SCIMUser": { + "type": "object", + "properties": { + "active": { + "type": "boolean" + }, + "emails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "display": { + "type": "string" + }, + "primary": { + "type": "boolean" + }, + "type": { + "type": "string" + }, + "value": { + "type": "string", + "format": "email" + } + } + } + }, + "groups": { + "type": "array", + "items": {} + }, + "id": { + "type": "string" + }, + "meta": { + "type": "object", + "properties": { + "resourceType": { + "type": "string" + } + } + }, + "name": { + "type": "object", + "properties": { + "familyName": { + "type": "string" + }, + "givenName": { + "type": "string" + } + } + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + }, + "userName": { + "type": "string" + } + } + }, "coderd.cspViolation": { "type": "object", "properties": { @@ -3428,7 +4068,6 @@ "format": "date-time" }, "user_id": { - "description": "NOTE: do not ever return the HashedSecret", "type": "string", "format": "uuid" } @@ -3451,6 +4090,15 @@ } } }, + "codersdk.AddLicenseRequest": { + "type": "object", + "required": ["license"], + "properties": { + "license": { + "type": "string" + } + } + }, "codersdk.AgentGitSSHKey": { "type": "object", "properties": { @@ -3503,6 +4151,17 @@ } } }, + "codersdk.AppearanceConfig": { + "type": "object", + "properties": { + "logo_url": { + "type": "string" + }, + "service_banner": { + "$ref": "#/definitions/codersdk.ServiceBannerConfig" + } + } + }, "codersdk.AssignableRoles": { "type": "object", "properties": { @@ -3758,6 +4417,20 @@ } } }, + "codersdk.CreateGroupRequest": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "name": { + "type": "string" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.CreateOrganizationRequest": { "type": "object", "required": ["name"], @@ -4350,6 +5023,64 @@ } } }, + "codersdk.Entitlement": { + "type": "string", + "enum": ["entitled", "grace_period", "not_entitled"], + "x-enum-varnames": [ + "EntitlementEntitled", + "EntitlementGracePeriod", + "EntitlementNotEntitled" + ] + }, + "codersdk.Entitlements": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "string" + } + }, + "experimental": { + "type": "boolean" + }, + "features": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.Feature" + } + }, + "has_license": { + "type": "boolean" + }, + "trial": { + "type": "boolean" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "codersdk.Feature": { + "type": "object", + "properties": { + "actual": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "entitlement": { + "$ref": "#/definitions/codersdk.Entitlement" + }, + "limit": { + "type": "integer" + } + } + }, "codersdk.GenerateAPIKeyResponse": { "type": "object", "properties": { @@ -4445,6 +5176,34 @@ } } }, + "codersdk.Group": { + "type": "object", + "properties": { + "avatar_url": { + "type": "string" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.User" + } + }, + "name": { + "type": "string" + }, + "organization_id": { + "type": "string", + "format": "uuid" + }, + "quota_allowance": { + "type": "integer" + } + } + }, "codersdk.Healthcheck": { "type": "object", "properties": { @@ -4462,6 +5221,27 @@ } } }, + "codersdk.License": { + "type": "object", + "properties": { + "claims": { + "description": "Claims are the JWT claims asserted by the license. Here we use\na generic string map to ensure that all data from the server is\nparsed verbatim, not just the fields this version of Coder\nunderstands.", + "type": "object", + "additionalProperties": true + }, + "id": { + "type": "integer" + }, + "uploaded_at": { + "type": "string", + "format": "date-time" + }, + "uuid": { + "type": "string", + "format": "uuid" + } + } + }, "codersdk.LogLevel": { "type": "string", "enum": ["trace", "debug", "info", "warn", "error"], @@ -4829,6 +5609,42 @@ } } }, + "codersdk.ProvisionerDaemon": { + "type": "object", + "properties": { + "created_at": { + "type": "string", + "format": "date-time" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "provisioners": { + "type": "array", + "items": { + "type": "string" + } + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "updated_at": { + "format": "date-time", + "allOf": [ + { + "$ref": "#/definitions/sql.NullTime" + } + ] + } + } + }, "codersdk.ProvisionerJob": { "type": "object", "properties": { @@ -4954,6 +5770,41 @@ } } }, + "codersdk.Replica": { + "type": "object", + "properties": { + "created_at": { + "description": "CreatedAt is the timestamp when the replica was first seen.", + "type": "string", + "format": "date-time" + }, + "database_latency": { + "description": "DatabaseLatency is the latency in microseconds to the database.", + "type": "integer" + }, + "error": { + "description": "Error is the replica error.", + "type": "string" + }, + "hostname": { + "description": "Hostname is the hostname of the replica.", + "type": "string" + }, + "id": { + "description": "ID is the unique identifier for the replica.", + "type": "string", + "format": "uuid" + }, + "region_id": { + "description": "RegionID is the region of the replica.", + "type": "integer" + }, + "relay_address": { + "description": "RelayAddress is the accessible address to relay DERP connections.", + "type": "string" + } + } + }, "codersdk.ResourceType": { "type": "string", "enum": [ @@ -5010,6 +5861,20 @@ } } }, + "codersdk.ServiceBannerConfig": { + "type": "object", + "properties": { + "background_color": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + }, "codersdk.SwaggerConfig": { "type": "object", "properties": { @@ -5178,6 +6043,73 @@ } } }, + "codersdk.TemplateRole": { + "type": "string", + "enum": ["admin", "use", ""], + "x-enum-varnames": [ + "TemplateRoleAdmin", + "TemplateRoleUse", + "TemplateRoleDeleted" + ] + }, + "codersdk.TemplateUser": { + "type": "object", + "required": ["created_at", "email", "id", "username"], + "properties": { + "avatar_url": { + "type": "string", + "format": "uri" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "email": { + "type": "string", + "format": "email" + }, + "id": { + "type": "string", + "format": "uuid" + }, + "last_seen_at": { + "type": "string", + "format": "date-time" + }, + "organization_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "role": { + "enum": ["admin", "use"], + "allOf": [ + { + "$ref": "#/definitions/codersdk.TemplateRole" + } + ] + }, + "roles": { + "type": "array", + "items": { + "$ref": "#/definitions/codersdk.Role" + } + }, + "status": { + "enum": ["active", "suspended"], + "allOf": [ + { + "$ref": "#/definitions/codersdk.UserStatus" + } + ] + }, + "username": { + "type": "string" + } + } + }, "codersdk.TemplateVersion": { "type": "object", "properties": { @@ -5280,6 +6212,23 @@ } } }, + "codersdk.UpdateTemplateACL": { + "type": "object", + "properties": { + "group_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + }, + "user_perms": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/codersdk.TemplateRole" + } + } + } + }, "codersdk.UpdateUserPasswordRequest": { "type": "object", "required": ["password"], @@ -5788,6 +6737,17 @@ } } }, + "codersdk.WorkspaceQuota": { + "type": "object", + "properties": { + "budget": { + "type": "integer" + }, + "credits_consumed": { + "type": "integer" + } + } + }, "codersdk.WorkspaceResource": { "type": "object", "properties": { @@ -5968,6 +6928,18 @@ } } }, + "sql.NullTime": { + "type": "object", + "properties": { + "time": { + "type": "string" + }, + "valid": { + "description": "Valid is true if Time is not NULL", + "type": "boolean" + } + } + }, "tailcfg.DERPMap": { "type": "object", "properties": { diff --git a/codersdk/apikey.go b/codersdk/apikey.go index fd896a0d29..739fe7d255 100644 --- a/codersdk/apikey.go +++ b/codersdk/apikey.go @@ -10,9 +10,9 @@ import ( "github.com/google/uuid" ) +// APIKey: do not ever return the HashedSecret type APIKey struct { - ID string `json:"id" validate:"required"` - // NOTE: do not ever return the HashedSecret + ID string `json:"id" validate:"required"` UserID uuid.UUID `json:"user_id" validate:"required" format:"uuid"` LastUsed time.Time `json:"last_used" validate:"required" format:"date-time"` ExpiresAt time.Time `json:"expires_at" validate:"required" format:"date-time"` diff --git a/codersdk/groups.go b/codersdk/groups.go index 0647efd6e9..b0608f3530 100644 --- a/codersdk/groups.go +++ b/codersdk/groups.go @@ -17,9 +17,9 @@ type CreateGroupRequest struct { } type Group struct { - ID uuid.UUID `json:"id"` + ID uuid.UUID `json:"id" format:"uuid"` Name string `json:"name"` - OrganizationID uuid.UUID `json:"organization_id"` + OrganizationID uuid.UUID `json:"organization_id" format:"uuid"` Members []User `json:"members"` AvatarURL string `json:"avatar_url"` QuotaAllowance int `json:"quota_allowance"` diff --git a/codersdk/licenses.go b/codersdk/licenses.go index 73118de5fd..3ede213e53 100644 --- a/codersdk/licenses.go +++ b/codersdk/licenses.go @@ -16,8 +16,8 @@ type AddLicenseRequest struct { type License struct { ID int32 `json:"id"` - UUID uuid.UUID `json:"uuid"` - UploadedAt time.Time `json:"uploaded_at"` + UUID uuid.UUID `json:"uuid" format:"uuid"` + UploadedAt time.Time `json:"uploaded_at" format:"date-time"` // Claims are the JWT claims asserted by the license. Here we use // a generic string map to ensure that all data from the server is // parsed verbatim, not just the fields this version of Coder diff --git a/codersdk/provisionerdaemons.go b/codersdk/provisionerdaemons.go index da0d2b67d0..c1b85345d0 100644 --- a/codersdk/provisionerdaemons.go +++ b/codersdk/provisionerdaemons.go @@ -37,9 +37,9 @@ const ( ) type ProvisionerDaemon struct { - ID uuid.UUID `json:"id"` - CreatedAt time.Time `json:"created_at"` - UpdatedAt sql.NullTime `json:"updated_at"` + ID uuid.UUID `json:"id" format:"uuid"` + CreatedAt time.Time `json:"created_at" format:"date-time"` + UpdatedAt sql.NullTime `json:"updated_at" format:"date-time"` Name string `json:"name"` Provisioners []ProvisionerType `json:"provisioners"` Tags map[string]string `json:"tags"` diff --git a/codersdk/replicas.go b/codersdk/replicas.go index e74af021ee..756ebcfcb7 100644 --- a/codersdk/replicas.go +++ b/codersdk/replicas.go @@ -12,16 +12,16 @@ import ( type Replica struct { // ID is the unique identifier for the replica. - ID uuid.UUID `json:"id"` + ID uuid.UUID `json:"id" format:"uuid"` // Hostname is the hostname of the replica. Hostname string `json:"hostname"` - // CreatedAt is when the replica was first seen. - CreatedAt time.Time `json:"created_at"` + // CreatedAt is the timestamp when the replica was first seen. + CreatedAt time.Time `json:"created_at" format:"date-time"` // RelayAddress is the accessible address to relay DERP connections. RelayAddress string `json:"relay_address"` // RegionID is the region of the replica. RegionID int32 `json:"region_id"` - // Error is the error. + // Error is the replica error. Error string `json:"error"` // DatabaseLatency is the latency in microseconds to the database. DatabaseLatency int32 `json:"database_latency"` diff --git a/codersdk/templates.go b/codersdk/templates.go index fce8b6f4c4..bf00bd7e3d 100644 --- a/codersdk/templates.go +++ b/codersdk/templates.go @@ -60,12 +60,12 @@ type TemplateACL struct { type TemplateGroup struct { Group - Role TemplateRole `json:"role"` + Role TemplateRole `json:"role" enums:"admin,use"` } type TemplateUser struct { User - Role TemplateRole `json:"role"` + Role TemplateRole `json:"role" enums:"admin,use"` } type UpdateTemplateACL struct { diff --git a/docs/api/builds.md b/docs/api/builds.md index cf90416777..d69028c041 100644 --- a/docs/api/builds.md +++ b/docs/api/builds.md @@ -515,61 +515,61 @@ curl -X GET http://coder-server:8080/api/v2/workspacebuilds/{workspacebuild}/res Status Code **200** -| Name | Type | Required | Restrictions | Description | -| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `[array item]` | array | false | | | -| `» agents` | array | false | | | -| `»» apps` | array | false | | | -| `»»» command` | string | false | | | -| `»»» display_name` | string | false | | DisplayName is a friendly name for the app. | -| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on
the client or not. | -| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | -| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | -| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | -| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | -| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. | -| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `»»» id` | string(uuid) | false | | | -| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | -| `»»» slug` | string | false | | Slug is a unique identifier within the agent. | -| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | -| `»»» url` | string | false | | URL is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | -| `»» architecture` | string | false | | | -| `»» connection_timeout_seconds` | integer | false | | | -| `»» created_at` | string(date-time) | false | | | -| `»» directory` | string | false | | | -| `»» disconnected_at` | string(date-time) | false | | | -| `»» environment_variables` | object | false | | | -| `»»» [any property]` | string | false | | | -| `»» first_connected_at` | string(date-time) | false | | | -| `»» id` | string(uuid) | false | | | -| `»» instance_id` | string | false | | | -| `»» last_connected_at` | string(date-time) | false | | | -| `»» latency` | object | false | | DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). | -| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | -| `»»»» latency_ms` | number | false | | | -| `»»»» preferred` | boolean | false | | | -| `»» name` | string | false | | | -| `»» operating_system` | string | false | | | -| `»» resource_id` | string(uuid) | false | | | -| `»» startup_script` | string | false | | | -| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | -| `»» troubleshooting_url` | string | false | | | -| `»» updated_at` | string(date-time) | false | | | -| `»» version` | string | false | | | -| `» created_at` | string(date-time) | false | | | -| `» daily_cost` | integer | false | | | -| `» hide` | boolean | false | | | -| `» icon` | string | false | | | -| `» id` | string(uuid) | false | | | -| `» job_id` | string(uuid) | false | | | -| `» metadata` | array | false | | | -| `»» key` | string | false | | | -| `»» sensitive` | boolean | false | | | -| `»» value` | string | false | | | -| `» name` | string | false | | | -| `» type` | string | false | | | -| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[array item]` | array | false | | | +| `» agents` | array | false | | | +| `»» apps` | array | false | | | +| `»»» command` | string | false | | | +| `»»» display_name` | string | false | | »»display name is a friendly name for the app. | +| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. | +| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | +| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | +| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | +| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | +| `»»»» url` | string | false | | »»»url specifies the endpoint to check for the app health. | +| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | +| `»»» id` | string(uuid) | false | | | +| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | +| `»»» slug` | string | false | | Slug is a unique identifier within the agent. | +| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. | +| `»»» url` | string | false | | »»url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | +| `»» architecture` | string | false | | | +| `»» connection_timeout_seconds` | integer | false | | | +| `»» created_at` | string(date-time) | false | | | +| `»» directory` | string | false | | | +| `»» disconnected_at` | string(date-time) | false | | | +| `»» environment_variables` | object | false | | | +| `»»» [any property]` | string | false | | | +| `»» first_connected_at` | string(date-time) | false | | | +| `»» id` | string(uuid) | false | | | +| `»» instance_id` | string | false | | | +| `»» last_connected_at` | string(date-time) | false | | | +| `»» latency` | object | false | | »latency is mapped by region name (e.g. "New York City", "Seattle"). | +| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | +| `»»»» latency_ms` | number | false | | | +| `»»»» preferred` | boolean | false | | | +| `»» name` | string | false | | | +| `»» operating_system` | string | false | | | +| `»» resource_id` | string(uuid) | false | | | +| `»» startup_script` | string | false | | | +| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | +| `»» troubleshooting_url` | string | false | | | +| `»» updated_at` | string(date-time) | false | | | +| `»» version` | string | false | | | +| `» created_at` | string(date-time) | false | | | +| `» daily_cost` | integer | false | | | +| `» hide` | boolean | false | | | +| `» icon` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» job_id` | string(uuid) | false | | | +| `» metadata` | array | false | | | +| `»» key` | string | false | | | +| `»» sensitive` | boolean | false | | | +| `»» value` | string | false | | | +| `» name` | string | false | | | +| `» type` | string | false | | | +| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | #### Enumerated Values @@ -884,91 +884,91 @@ curl -X GET http://coder-server:8080/api/v2/workspaces/{id}/builds \ Status Code **200** -| Name | Type | Required | Restrictions | Description | -| -------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `[array item]` | array | false | | | -| `» build_number` | integer | false | | | -| `» created_at` | string(date-time) | false | | | -| `» daily_cost` | integer | false | | | -| `» deadline` | string(date-time) | false | | | -| `» id` | string(uuid) | false | | | -| `» initiator_id` | string(uuid) | false | | | -| `» initiator_name` | string | false | | | -| `» job` | [codersdk.ProvisionerJob](schemas.md#codersdkprovisionerjob) | false | | | -| `»» canceled_at` | string(date-time) | false | | | -| `»» completed_at` | string(date-time) | false | | | -| `»» created_at` | string(date-time) | false | | | -| `»» error` | string | false | | | -| `»» file_id` | string(uuid) | false | | | -| `»» id` | string(uuid) | false | | | -| `»» started_at` | string(date-time) | false | | | -| `»» status` | [codersdk.ProvisionerJobStatus](schemas.md#codersdkprovisionerjobstatus) | false | | | -| `»» tags` | object | false | | | -| `»»» [any property]` | string | false | | | -| `»» worker_id` | string(uuid) | false | | | -| `» reason` | [codersdk.BuildReason](schemas.md#codersdkbuildreason) | false | | | -| `» resources` | array | false | | | -| `»» agents` | array | false | | | -| `»»» apps` | array | false | | | -| `»»»» command` | string | false | | | -| `»»»» display_name` | string | false | | DisplayName is a friendly name for the app. | -| `»»»» external` | boolean | false | | External specifies whether the URL should be opened externally on
the client or not. | -| `»»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | -| `»»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | -| `»»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | -| `»»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | -| `»»»»» url` | string | false | | URL specifies the endpoint to check for the app health. | -| `»»»» icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `»»»» id` | string(uuid) | false | | | -| `»»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | -| `»»»» slug` | string | false | | Slug is a unique identifier within the agent. | -| `»»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | -| `»»»» url` | string | false | | URL is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | -| `»»» architecture` | string | false | | | -| `»»» connection_timeout_seconds` | integer | false | | | -| `»»» created_at` | string(date-time) | false | | | -| `»»» directory` | string | false | | | -| `»»» disconnected_at` | string(date-time) | false | | | -| `»»» environment_variables` | object | false | | | -| `»»»» [any property]` | string | false | | | -| `»»» first_connected_at` | string(date-time) | false | | | -| `»»» id` | string(uuid) | false | | | -| `»»» instance_id` | string | false | | | -| `»»» last_connected_at` | string(date-time) | false | | | -| `»»» latency` | object | false | | DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). | -| `»»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | -| `»»»»» latency_ms` | number | false | | | -| `»»»»» preferred` | boolean | false | | | -| `»»» name` | string | false | | | -| `»»» operating_system` | string | false | | | -| `»»» resource_id` | string(uuid) | false | | | -| `»»» startup_script` | string | false | | | -| `»»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | -| `»»» troubleshooting_url` | string | false | | | -| `»»» updated_at` | string(date-time) | false | | | -| `»»» version` | string | false | | | -| `»» created_at` | string(date-time) | false | | | -| `»» daily_cost` | integer | false | | | -| `»» hide` | boolean | false | | | -| `»» icon` | string | false | | | -| `»» id` | string(uuid) | false | | | -| `»» job_id` | string(uuid) | false | | | -| `»» metadata` | array | false | | | -| `»»» key` | string | false | | | -| `»»» sensitive` | boolean | false | | | -| `»»» value` | string | false | | | -| `»» name` | string | false | | | -| `»» type` | string | false | | | -| `»» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | -| `» status` | [codersdk.WorkspaceStatus](schemas.md#codersdkworkspacestatus) | false | | | -| `» template_version_id` | string(uuid) | false | | | -| `» template_version_name` | string | false | | | -| `» transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | -| `» updated_at` | string(date-time) | false | | | -| `» workspace_id` | string(uuid) | false | | | -| `» workspace_name` | string | false | | | -| `» workspace_owner_id` | string(uuid) | false | | | -| `» workspace_owner_name` | string | false | | | +| Name | Type | Required | Restrictions | Description | +| -------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[array item]` | array | false | | | +| `» build_number` | integer | false | | | +| `» created_at` | string(date-time) | false | | | +| `» daily_cost` | integer | false | | | +| `» deadline` | string(date-time) | false | | | +| `» id` | string(uuid) | false | | | +| `» initiator_id` | string(uuid) | false | | | +| `» initiator_name` | string | false | | | +| `» job` | [codersdk.ProvisionerJob](schemas.md#codersdkprovisionerjob) | false | | | +| `»» canceled_at` | string(date-time) | false | | | +| `»» completed_at` | string(date-time) | false | | | +| `»» created_at` | string(date-time) | false | | | +| `»» error` | string | false | | | +| `»» file_id` | string(uuid) | false | | | +| `»» id` | string(uuid) | false | | | +| `»» started_at` | string(date-time) | false | | | +| `»» status` | [codersdk.ProvisionerJobStatus](schemas.md#codersdkprovisionerjobstatus) | false | | | +| `»» tags` | object | false | | | +| `»»» [any property]` | string | false | | | +| `»» worker_id` | string(uuid) | false | | | +| `» reason` | [codersdk.BuildReason](schemas.md#codersdkbuildreason) | false | | | +| `» resources` | array | false | | | +| `»» agents` | array | false | | | +| `»»» apps` | array | false | | | +| `»»»» command` | string | false | | | +| `»»»» display_name` | string | false | | »»»display name is a friendly name for the app. | +| `»»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. | +| `»»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | +| `»»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | +| `»»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | +| `»»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | +| `»»»»» url` | string | false | | »»»»url specifies the endpoint to check for the app health. | +| `»»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | +| `»»»» id` | string(uuid) | false | | | +| `»»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | +| `»»»» slug` | string | false | | Slug is a unique identifier within the agent. | +| `»»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. | +| `»»»» url` | string | false | | »»»url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | +| `»»» architecture` | string | false | | | +| `»»» connection_timeout_seconds` | integer | false | | | +| `»»» created_at` | string(date-time) | false | | | +| `»»» directory` | string | false | | | +| `»»» disconnected_at` | string(date-time) | false | | | +| `»»» environment_variables` | object | false | | | +| `»»»» [any property]` | string | false | | | +| `»»» first_connected_at` | string(date-time) | false | | | +| `»»» id` | string(uuid) | false | | | +| `»»» instance_id` | string | false | | | +| `»»» last_connected_at` | string(date-time) | false | | | +| `»»» latency` | object | false | | »»latency is mapped by region name (e.g. "New York City", "Seattle"). | +| `»»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | +| `»»»»» latency_ms` | number | false | | | +| `»»»»» preferred` | boolean | false | | | +| `»»» name` | string | false | | | +| `»»» operating_system` | string | false | | | +| `»»» resource_id` | string(uuid) | false | | | +| `»»» startup_script` | string | false | | | +| `»»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | +| `»»» troubleshooting_url` | string | false | | | +| `»»» updated_at` | string(date-time) | false | | | +| `»»» version` | string | false | | | +| `»» created_at` | string(date-time) | false | | | +| `»» daily_cost` | integer | false | | | +| `»» hide` | boolean | false | | | +| `»» icon` | string | false | | | +| `»» id` | string(uuid) | false | | | +| `»» job_id` | string(uuid) | false | | | +| `»» metadata` | array | false | | | +| `»»» key` | string | false | | | +| `»»» sensitive` | boolean | false | | | +| `»»» value` | string | false | | | +| `»» name` | string | false | | | +| `»» type` | string | false | | | +| `»» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | +| `» status` | [codersdk.WorkspaceStatus](schemas.md#codersdkworkspacestatus) | false | | | +| `» template_version_id` | string(uuid) | false | | | +| `» template_version_name` | string | false | | | +| `» transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | +| `» updated_at` | string(date-time) | false | | | +| `» workspace_id` | string(uuid) | false | | | +| `» workspace_name` | string | false | | | +| `» workspace_owner_id` | string(uuid) | false | | | +| `» workspace_owner_name` | string | false | | | #### Enumerated Values diff --git a/docs/api/enterprise.md b/docs/api/enterprise.md new file mode 100644 index 0000000000..b6df74df03 --- /dev/null +++ b/docs/api/enterprise.md @@ -0,0 +1,980 @@ +# Enterprise + +> This page is incomplete, stay tuned. + +## Get appearance + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/appearance \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /appearance` + +### Example responses + +> 200 Response + +```json +{ + "logo_url": "string", + "service_banner": { + "background_color": "string", + "enabled": true, + "message": "string" + } +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AppearanceConfig](schemas.md#codersdkappearanceconfig) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Update appearance + +### Code samples + +```shell +# Example request using curl +curl -X PUT http://coder-server:8080/api/v2/appearance \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`PUT /appearance` + +> Body parameter + +```json +{ + "logo_url": "string", + "service_banner": { + "background_color": "string", + "enabled": true, + "message": "string" + } +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | ---------------------------------------------------------------- | -------- | ------------------------- | +| `body` | body | [codersdk.AppearanceConfig](schemas.md#codersdkappearanceconfig) | true | Update appearance request | + +### Example responses + +> 200 Response + +```json +{ + "logo_url": "string", + "service_banner": { + "background_color": "string", + "enabled": true, + "message": "string" + } +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AppearanceConfig](schemas.md#codersdkappearanceconfig) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get entitlements + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/entitlements \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /entitlements` + +### Example responses + +> 200 Response + +```json +{ + "errors": ["string"], + "experimental": true, + "features": { + "property1": { + "actual": 0, + "enabled": true, + "entitlement": "entitled", + "limit": 0 + }, + "property2": { + "actual": 0, + "enabled": true, + "entitlement": "entitled", + "limit": 0 + } + }, + "has_license": true, + "trial": true, + "warnings": ["string"] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Entitlements](schemas.md#codersdkentitlements) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get groups + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/groups \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /groups` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | + +### Example responses + +> 200 Response + +```json +[ + { + "avatar_url": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "members": [ + { + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "quota_allowance": 0 + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Group](schemas.md#codersdkgroup) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| --------------------- | ---------------------------------------------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» avatar_url` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» members` | array | false | | | +| `»» avatar_url` | string(uri) | false | | | +| `»» created_at` | string(date-time) | true | | | +| `»» email` | string(email) | true | | | +| `»» id` | string(uuid) | true | | | +| `»» last_seen_at` | string(date-time) | false | | | +| `»» organization_ids` | array | false | | | +| `»» roles` | array | false | | | +| `»»» display_name` | string | false | | | +| `»»» name` | string | false | | | +| `»» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | | +| `»» username` | string | true | | | +| `» name` | string | false | | | +| `» organization_id` | string(uuid) | false | | | +| `» quota_allowance` | integer | false | | | + +#### Enumerated Values + +| Property | Value | +| -------- | ----------- | +| `status` | `active` | +| `status` | `suspended` | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get group by name + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/groups/{groupName} \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /groups/{groupName}` + +### Parameters + +| Name | In | Type | Required | Description | +| ----------- | ---- | ------ | -------- | ----------- | +| `groupName` | path | string | true | Group name | + +### Example responses + +> 200 Response + +```json +{ + "avatar_url": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "members": [ + { + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "quota_allowance": 0 +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Group](schemas.md#codersdkgroup) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Delete license + +### Code samples + +```shell +# Example request using curl +curl -X DELETE http://coder-server:8080/api/v2/license/{id} \ + -H 'Coder-Session-Token: API_KEY' +``` + +`DELETE /license/{id}` + +### Parameters + +| Name | In | Type | Required | Description | +| ---- | ---- | -------------- | -------- | ----------- | +| `id` | path | string(number) | true | License ID | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get licenses + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/licenses \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /licenses` + +### Example responses + +> 200 Response + +```json +[ + { + "claims": {}, + "id": 0, + "uploaded_at": "2019-08-24T14:15:22Z", + "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.License](schemas.md#codersdklicense) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| --------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `[array item]` | array | false | | | +| `» claims` | object | false | | Claims are the JWT claims asserted by the license. Here we use a generic string map to ensure that all data from the server is parsed verbatim, not just the fields this version of Coder understands. | +| `» id` | integer | false | | | +| `» uploaded_at` | string(date-time) | false | | | +| `» uuid` | string(uuid) | false | | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get groups by organization + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /organizations/{organization}/groups` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | + +### Example responses + +> 200 Response + +```json +[ + { + "avatar_url": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "members": [ + { + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "quota_allowance": 0 + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Group](schemas.md#codersdkgroup) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| --------------------- | ---------------------------------------------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» avatar_url` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» members` | array | false | | | +| `»» avatar_url` | string(uri) | false | | | +| `»» created_at` | string(date-time) | true | | | +| `»» email` | string(email) | true | | | +| `»» id` | string(uuid) | true | | | +| `»» last_seen_at` | string(date-time) | false | | | +| `»» organization_ids` | array | false | | | +| `»» roles` | array | false | | | +| `»»» display_name` | string | false | | | +| `»»» name` | string | false | | | +| `»» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | | +| `»» username` | string | true | | | +| `» name` | string | false | | | +| `» organization_id` | string(uuid) | false | | | +| `» quota_allowance` | integer | false | | | + +#### Enumerated Values + +| Property | Value | +| -------- | ----------- | +| `status` | `active` | +| `status` | `suspended` | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get provisioner daemons + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerdaemons \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /organizations/{organization}/provisionerdaemons` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | + +### Example responses + +> 200 Response + +```json +[ + { + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "name": "string", + "provisioners": ["string"], + "tags": { + "property1": "string", + "property2": "string" + }, + "updated_at": { + "time": "string", + "valid": true + } + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.ProvisionerDaemon](schemas.md#codersdkprovisionerdaemon) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| ------------------- | -------------------------------------- | -------- | ------------ | --------------------------------- | +| `[array item]` | array | false | | | +| `» created_at` | string(date-time) | false | | | +| `» id` | string(uuid) | false | | | +| `» name` | string | false | | | +| `» provisioners` | array | false | | | +| `» tags` | object | false | | | +| `»» [any property]` | string | false | | | +| `» updated_at` | [sql.NullTime](schemas.md#sqlnulltime) | false | | | +| `»» time` | string | false | | | +| `»» valid` | boolean | false | | Valid is true if Time is not NULL | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Serve provisioner daemon + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerdaemons/serve \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /organizations/{organization}/provisionerdaemons/serve` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------------ | -------- | --------------- | +| `organization` | path | string(uuid) | true | Organization ID | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------------------------ | ------------------- | ------ | +| 101 | [Switching Protocols](https://tools.ietf.org/html/rfc7231#section-6.2.2) | Switching Protocols | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get active replicas + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/replicas \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /replicas` + +### Example responses + +> 200 Response + +```json +[ + { + "created_at": "2019-08-24T14:15:22Z", + "database_latency": 0, + "error": "string", + "hostname": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "region_id": 0, + "relay_address": "string" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Replica](schemas.md#codersdkreplica) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| -------------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------------ | +| `[array item]` | array | false | | | +| `» created_at` | string(date-time) | false | | Created at is the timestamp when the replica was first seen. | +| `» database_latency` | integer | false | | Database latency is the latency in microseconds to the database. | +| `» error` | string | false | | Error is the replica error. | +| `» hostname` | string | false | | Hostname is the hostname of the replica. | +| `» id` | string(uuid) | false | | ID is the unique identifier for the replica. | +| `» region_id` | integer | false | | Region ID is the region of the replica. | +| `» relay_address` | string | false | | Relay address is the accessible address to relay DERP connections. | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## SCIM 2.0: Create new user + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/scim/v2/Users \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /scim/v2/Users` + +> Body parameter + +```json +{ + "active": true, + "emails": [ + { + "display": "string", + "primary": true, + "type": "string", + "value": "user@example.com" + } + ], + "groups": [null], + "id": "string", + "meta": { + "resourceType": "string" + }, + "name": { + "familyName": "string", + "givenName": "string" + }, + "schemas": ["string"], + "userName": "string" +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | -------------------------------------------- | -------- | ----------- | +| `body` | body | [coderd.SCIMUser](schemas.md#coderdscimuser) | true | New user | + +### Example responses + +> 200 Response + +```json +{ + "active": true, + "emails": [ + { + "display": "string", + "primary": true, + "type": "string", + "value": "user@example.com" + } + ], + "groups": [null], + "id": "string", + "meta": { + "resourceType": "string" + }, + "name": { + "familyName": "string", + "givenName": "string" + }, + "schemas": ["string"], + "userName": "string" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [coderd.SCIMUser](schemas.md#coderdscimuser) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## SCIM 2.0: Get user by ID + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/scim/v2/Users/{id} \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /scim/v2/Users/{id}` + +### Parameters + +| Name | In | Type | Required | Description | +| ---- | ---- | ------------ | -------- | ----------- | +| `id` | path | string(uuid) | true | User ID | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | -------------------------------------------------------------- | ----------- | ------ | +| 404 | [Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | Not Found | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## SCIM 2.0: Update user account + +### Code samples + +```shell +# Example request using curl +curl -X PATCH http://coder-server:8080/api/v2/scim/v2/Users/{id} \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/scim+json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`PATCH /scim/v2/Users/{id}` + +> Body parameter + +```json +{ + "active": true, + "emails": [ + { + "display": "string", + "primary": true, + "type": "string", + "value": "user@example.com" + } + ], + "groups": [null], + "id": "string", + "meta": { + "resourceType": "string" + }, + "name": { + "familyName": "string", + "givenName": "string" + }, + "schemas": ["string"], + "userName": "string" +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | -------------------------------------------- | -------- | ------------------- | +| `id` | path | string(uuid) | true | User ID | +| `body` | body | [coderd.SCIMUser](schemas.md#coderdscimuser) | true | Update user request | + +### Example responses + +> 200 Response + +```json +{ + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.User](schemas.md#codersdkuser) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get template ACLs + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /templates/{template}/acl` + +### Parameters + +| Name | In | Type | Required | Description | +| ---------- | ---- | ------------ | -------- | ----------- | +| `template` | path | string(uuid) | true | Template ID | + +### Example responses + +> 200 Response + +```json +[ + { + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "role": "admin", + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.TemplateUser](schemas.md#codersdktemplateuser) | + +

Response Schema

+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| -------------------- | -------------------------------------------------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» avatar_url` | string(uri) | false | | | +| `» created_at` | string(date-time) | true | | | +| `» email` | string(email) | true | | | +| `» id` | string(uuid) | true | | | +| `» last_seen_at` | string(date-time) | false | | | +| `» organization_ids` | array | false | | | +| `» role` | [codersdk.TemplateRole](schemas.md#codersdktemplaterole) | false | | | +| `» roles` | array | false | | | +| `»» display_name` | string | false | | | +| `»» name` | string | false | | | +| `» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | | +| `» username` | string | true | | | + +#### Enumerated Values + +| Property | Value | +| -------- | ----------- | +| `role` | `admin` | +| `role` | `use` | +| `status` | `active` | +| `status` | `suspended` | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Update template ACL + +### Code samples + +```shell +# Example request using curl +curl -X PATCH http://coder-server:8080/api/v2/templates/{template}/acl \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`PATCH /templates/{template}/acl` + +> Body parameter + +```json +{ + "group_perms": { + "property1": "admin", + "property2": "admin" + }, + "user_perms": { + "property1": "admin", + "property2": "admin" + } +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ---------- | ---- | ------------------------------------------------------------------ | -------- | ----------------------- | +| `template` | path | string(uuid) | true | Template ID | +| `body` | body | [codersdk.UpdateTemplateACL](schemas.md#codersdkupdatetemplateacl) | true | Update template request | + +### Example responses + +> 200 Response + +```json +{ + "detail": "string", + "message": "string", + "validations": [ + { + "detail": "string", + "field": "string" + } + ] +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Get workspace quota by user + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/workspace-quota/{user} \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /workspace-quota/{user}` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | ------ | -------- | -------------------- | +| `user` | path | string | true | User ID, name, or me | + +### Example responses + +> 200 Response + +```json +{ + "budget": 0, + "credits_consumed": 0 +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.WorkspaceQuota](schemas.md#codersdkworkspacequota) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). diff --git a/docs/api/organizations.md b/docs/api/organizations.md index 18d4d70192..825f76f8a9 100644 --- a/docs/api/organizations.md +++ b/docs/api/organizations.md @@ -2,6 +2,55 @@ > This page is incomplete, stay tuned. +## Add new license + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/licenses \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /licenses` + +> Body parameter + +```json +{ + "license": "string" +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | ------------------------------------------------------------------ | -------- | ------------------- | +| `body` | body | [codersdk.AddLicenseRequest](schemas.md#codersdkaddlicenserequest) | true | Add license request | + +### Example responses + +> 201 Response + +```json +{ + "claims": {}, + "id": 0, + "uploaded_at": "2019-08-24T14:15:22Z", + "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------------ | ----------- | ---------------------------------------------- | +| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.License](schemas.md#codersdklicense) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Create organization ### Code samples diff --git a/docs/api/schemas.md b/docs/api/schemas.md index edb3d95035..ed546daf87 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -2,6 +2,53 @@ > This page is incomplete, stay tuned. +## coderd.SCIMUser + +```json +{ + "active": true, + "emails": [ + { + "display": "string", + "primary": true, + "type": "string", + "value": "user@example.com" + } + ], + "groups": [null], + "id": "string", + "meta": { + "resourceType": "string" + }, + "name": { + "familyName": "string", + "givenName": "string" + }, + "schemas": ["string"], + "userName": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------------- | ------------------ | -------- | ------------ | ----------- | +| `active` | boolean | false | | | +| `emails` | array of object | false | | | +| `» display` | string | false | | | +| `» primary` | boolean | false | | | +| `» type` | string | false | | | +| `» value` | string | false | | | +| `groups` | array of undefined | false | | | +| `id` | string | false | | | +| `meta` | object | false | | | +| `» resourceType` | string | false | | | +| `name` | object | false | | | +| `» familyName` | string | false | | | +| `» givenName` | string | false | | | +| `schemas` | array of string | false | | | +| `userName` | string | false | | | + ## coderd.cspViolation ```json @@ -34,17 +81,17 @@ ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------------ | -------------------------------------------- | -------- | ------------ | ------------------------------------------- | -| `created_at` | string | true | | | -| `expires_at` | string | true | | | -| `id` | string | true | | | -| `last_used` | string | true | | | -| `lifetime_seconds` | integer | true | | | -| `login_type` | [codersdk.LoginType](#codersdklogintype) | true | | | -| `scope` | [codersdk.APIKeyScope](#codersdkapikeyscope) | true | | | -| `updated_at` | string | true | | | -| `user_id` | string | true | | User ID do not ever return the HashedSecret | +| Name | Type | Required | Restrictions | Description | +| ------------------ | -------------------------------------------- | -------- | ------------ | ----------- | +| `created_at` | string | true | | | +| `expires_at` | string | true | | | +| `id` | string | true | | | +| `last_used` | string | true | | | +| `lifetime_seconds` | integer | true | | | +| `login_type` | [codersdk.LoginType](#codersdklogintype) | true | | | +| `scope` | [codersdk.APIKeyScope](#codersdkapikeyscope) | true | | | +| `updated_at` | string | true | | | +| `user_id` | string | true | | | #### Enumerated Values @@ -88,6 +135,20 @@ | `document` | string | true | | | | `signature` | string | true | | | +## codersdk.AddLicenseRequest + +```json +{ + "license": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| --------- | ------ | -------- | ------------ | ----------- | +| `license` | string | true | | | + ## codersdk.AgentGitSSHKey ```json @@ -146,6 +207,26 @@ | ----------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------ | | `report_interval` | integer | false | | Report interval is the duration after which the agent should send stats again. | +## codersdk.AppearanceConfig + +```json +{ + "logo_url": "string", + "service_banner": { + "background_color": "string", + "enabled": true, + "message": "string" + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------------- | ------------------------------------------------------------ | -------- | ------------ | ----------- | +| `logo_url` | string | false | | | +| `service_banner` | [codersdk.ServiceBannerConfig](#codersdkservicebannerconfig) | false | | | + ## codersdk.AssignableRoles ```json @@ -565,6 +646,24 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `organization_id` | string | false | | | | `user_id` | string | false | | | +## codersdk.CreateGroupRequest + +```json +{ + "avatar_url": "string", + "name": "string", + "quota_allowance": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----------------- | ------- | -------- | ------------ | ----------- | +| `avatar_url` | string | false | | | +| `name` | string | false | | | +| `quota_allowance` | integer | false | | | + ## codersdk.CreateOrganizationRequest ```json @@ -2148,6 +2247,80 @@ CreateParameterRequest is a structure used to create a new parameter value for a | `usage` | string | false | | | | `value` | integer | false | | | +## codersdk.Entitlement + +```json +"entitled" +``` + +### Properties + +#### Enumerated Values + +| Value | +| -------------- | +| `entitled` | +| `grace_period` | +| `not_entitled` | + +## codersdk.Entitlements + +```json +{ + "errors": ["string"], + "experimental": true, + "features": { + "property1": { + "actual": 0, + "enabled": true, + "entitlement": "entitled", + "limit": 0 + }, + "property2": { + "actual": 0, + "enabled": true, + "entitlement": "entitled", + "limit": 0 + } + }, + "has_license": true, + "trial": true, + "warnings": ["string"] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ------------------------------------ | -------- | ------------ | ----------- | +| `errors` | array of string | false | | | +| `experimental` | boolean | false | | | +| `features` | object | false | | | +| » `[any property]` | [codersdk.Feature](#codersdkfeature) | false | | | +| `has_license` | boolean | false | | | +| `trial` | boolean | false | | | +| `warnings` | array of string | false | | | + +## codersdk.Feature + +```json +{ + "actual": 0, + "enabled": true, + "entitlement": "entitled", + "limit": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------- | -------------------------------------------- | -------- | ------------ | ----------- | +| `actual` | integer | false | | | +| `enabled` | boolean | false | | | +| `entitlement` | [codersdk.Entitlement](#codersdkentitlement) | false | | | +| `limit` | integer | false | | | + ## codersdk.GenerateAPIKeyResponse ```json @@ -2273,6 +2446,47 @@ CreateParameterRequest is a structure used to create a new parameter value for a | ---------------- | ------ | -------- | ------------ | ----------- | | `json_web_token` | string | true | | | +## codersdk.Group + +```json +{ + "avatar_url": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "members": [ + { + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "quota_allowance": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----------------- | --------------------------------------- | -------- | ------------ | ----------- | +| `avatar_url` | string | false | | | +| `id` | string | false | | | +| `members` | array of [codersdk.User](#codersdkuser) | false | | | +| `name` | string | false | | | +| `organization_id` | string | false | | | +| `quota_allowance` | integer | false | | | + ## codersdk.Healthcheck ```json @@ -2291,6 +2505,26 @@ CreateParameterRequest is a structure used to create a new parameter value for a | `threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | | `url` | string | false | | URL specifies the endpoint to check for the app health. | +## codersdk.License + +```json +{ + "claims": {}, + "id": 0, + "uploaded_at": "2019-08-24T14:15:22Z", + "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `claims` | object | false | | Claims are the JWT claims asserted by the license. Here we use a generic string map to ensure that all data from the server is parsed verbatim, not just the fields this version of Coder understands. | +| `id` | integer | false | | | +| `uploaded_at` | string | false | | | +| `uuid` | string | false | | | + ## codersdk.LogLevel ```json @@ -3010,6 +3244,37 @@ Parameter represents a set value for the scope. | `daemons` | [codersdk.DeploymentConfigField-int](#codersdkdeploymentconfigfield-int) | false | | | | `force_cancel_interval` | [codersdk.DeploymentConfigField-time_Duration](#codersdkdeploymentconfigfield-time_duration) | false | | | +## codersdk.ProvisionerDaemon + +```json +{ + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "name": "string", + "provisioners": ["string"], + "tags": { + "property1": "string", + "property2": "string" + }, + "updated_at": { + "time": "string", + "valid": true + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ---------------------------- | -------- | ------------ | ----------- | +| `created_at` | string | false | | | +| `id` | string | false | | | +| `name` | string | false | | | +| `provisioners` | array of string | false | | | +| `tags` | object | false | | | +| » `[any property]` | string | false | | | +| `updated_at` | [sql.NullTime](#sqlnulltime) | false | | | + ## codersdk.ProvisionerJob ```json @@ -3160,6 +3425,32 @@ Parameter represents a set value for the scope. | `api` | [codersdk.DeploymentConfigField-int](#codersdkdeploymentconfigfield-int) | false | | | | `disable_all` | [codersdk.DeploymentConfigField-bool](#codersdkdeploymentconfigfield-bool) | false | | | +## codersdk.Replica + +```json +{ + "created_at": "2019-08-24T14:15:22Z", + "database_latency": 0, + "error": "string", + "hostname": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "region_id": 0, + "relay_address": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ------- | -------- | ------------ | ------------------------------------------------------------------ | +| `created_at` | string | false | | Created at is the timestamp when the replica was first seen. | +| `database_latency` | integer | false | | Database latency is the latency in microseconds to the database. | +| `error` | string | false | | Error is the replica error. | +| `hostname` | string | false | | Hostname is the hostname of the replica. | +| `id` | string | false | | ID is the unique identifier for the replica. | +| `region_id` | integer | false | | Region ID is the region of the replica. | +| `relay_address` | string | false | | Relay address is the accessible address to relay DERP connections. | + ## codersdk.ResourceType ```json @@ -3221,6 +3512,24 @@ Parameter represents a set value for the scope. | `display_name` | string | false | | | | `name` | string | false | | | +## codersdk.ServiceBannerConfig + +```json +{ + "background_color": "string", + "enabled": true, + "message": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ------- | -------- | ------------ | ----------- | +| `background_color` | string | false | | | +| `enabled` | boolean | false | | | +| `message` | string | false | | | + ## codersdk.SwaggerConfig ```json @@ -3552,6 +3861,68 @@ Parameter represents a set value for the scope. | `tags` | array of string | false | | | | `url` | string | false | | | +## codersdk.TemplateRole + +```json +"admin" +``` + +### Properties + +#### Enumerated Values + +| Value | +| ------- | +| `admin` | +| `use` | +| `` | + +## codersdk.TemplateUser + +```json +{ + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "role": "admin", + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ---------------------------------------------- | -------- | ------------ | ----------- | +| `avatar_url` | string | false | | | +| `created_at` | string | true | | | +| `email` | string | true | | | +| `id` | string | true | | | +| `last_seen_at` | string | false | | | +| `organization_ids` | array of string | false | | | +| `role` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | +| `roles` | array of [codersdk.Role](#codersdkrole) | false | | | +| `status` | [codersdk.UserStatus](#codersdkuserstatus) | false | | | +| `username` | string | true | | | + +#### Enumerated Values + +| Property | Value | +| -------- | ----------- | +| `role` | `admin` | +| `role` | `use` | +| `status` | `active` | +| `status` | `suspended` | + ## codersdk.TemplateVersion ```json @@ -3721,6 +4092,30 @@ Parameter represents a set value for the scope. | ------- | --------------- | -------- | ------------ | ----------- | | `roles` | array of string | false | | | +## codersdk.UpdateTemplateACL + +```json +{ + "group_perms": { + "property1": "admin", + "property2": "admin" + }, + "user_perms": { + "property1": "admin", + "property2": "admin" + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ---------------------------------------------- | -------- | ------------ | ----------- | +| `group_perms` | object | false | | | +| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | +| `user_perms` | object | false | | | +| » `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | + ## codersdk.UpdateUserPasswordRequest ```json @@ -4510,6 +4905,22 @@ Parameter represents a set value for the scope. | `transition` | `stop` | | `transition` | `delete` | +## codersdk.WorkspaceQuota + +```json +{ + "budget": 0, + "credits_consumed": 0 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ------- | -------- | ------------ | ----------- | +| `budget` | integer | false | | | +| `credits_consumed` | integer | false | | | + ## codersdk.WorkspaceResource ```json @@ -4887,6 +5298,22 @@ Parameter represents a set value for the scope. | `source_value` | string | false | | | | `updated_at` | string | false | | | +## sql.NullTime + +```json +{ + "time": "string", + "valid": true +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------- | ------- | -------- | ------------ | --------------------------------- | +| `time` | string | false | | | +| `valid` | boolean | false | | Valid is true if Time is not NULL | + ## tailcfg.DERPMap ```json diff --git a/docs/api/templates.md b/docs/api/templates.md index ccab73d4ce..dc29086ca6 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -2,6 +2,77 @@ > This page is incomplete, stay tuned. +## Create group for organization + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/groups \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /organizations/{organization}/groups` + +> Body parameter + +```json +{ + "avatar_url": "string", + "name": "string", + "quota_allowance": 0 +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | -------------------------------------------------------------------- | -------- | -------------------- | +| `organization` | path | string | true | Organization ID | +| `body` | body | [codersdk.CreateGroupRequest](schemas.md#codersdkcreategrouprequest) | true | Create group request | + +### Example responses + +> 201 Response + +```json +{ + "avatar_url": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "members": [ + { + "avatar_url": "http://example.com", + "created_at": "2019-08-24T14:15:22Z", + "email": "user@example.com", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_seen_at": "2019-08-24T14:15:22Z", + "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "roles": [ + { + "display_name": "string", + "name": "string" + } + ], + "status": "active", + "username": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "quota_allowance": 0 +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------------ | ----------- | ------------------------------------------ | +| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.Group](schemas.md#codersdkgroup) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Get templates by organization ### Code samples @@ -68,29 +139,29 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat Status Code **200** -| Name | Type | Required | Restrictions | Description | -| ------------------------------------ | ---------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------ | -| `[array item]` | array | false | | | -| `» active_user_count` | integer | false | | ActiveUserCount is set to -1 when loading. | -| `» active_version_id` | string(uuid) | false | | | -| `» allow_user_cancel_workspace_jobs` | boolean | false | | | -| `» build_time_stats` | [codersdk.TemplateBuildTimeStats](schemas.md#codersdktemplatebuildtimestats) | false | | | -| `»» [any property]` | [codersdk.TransitionStats](schemas.md#codersdktransitionstats) | false | | | -| `»»» p50` | integer | false | | | -| `»»» p95` | integer | false | | | -| `» created_at` | string(date-time) | false | | | -| `» created_by_id` | string(uuid) | false | | | -| `» created_by_name` | string | false | | | -| `» default_ttl_ms` | integer | false | | | -| `» description` | string | false | | | -| `» display_name` | string | false | | | -| `» icon` | string | false | | | -| `» id` | string(uuid) | false | | | -| `» name` | string | false | | | -| `» organization_id` | string(uuid) | false | | | -| `» provisioner` | string | false | | | -| `» updated_at` | string(date-time) | false | | | -| `» workspace_owner_count` | integer | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------------------------ | ---------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------- | +| `[array item]` | array | false | | | +| `» active_user_count` | integer | false | | Active user count is set to -1 when loading. | +| `» active_version_id` | string(uuid) | false | | | +| `» allow_user_cancel_workspace_jobs` | boolean | false | | | +| `» build_time_stats` | [codersdk.TemplateBuildTimeStats](schemas.md#codersdktemplatebuildtimestats) | false | | | +| `»» [any property]` | [codersdk.TransitionStats](schemas.md#codersdktransitionstats) | false | | | +| `»»» p50` | integer | false | | | +| `»»» p95` | integer | false | | | +| `» created_at` | string(date-time) | false | | | +| `» created_by_id` | string(uuid) | false | | | +| `» created_by_name` | string | false | | | +| `» default_ttl_ms` | integer | false | | | +| `» description` | string | false | | | +| `» display_name` | string | false | | | +| `» icon` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» name` | string | false | | | +| `» organization_id` | string(uuid) | false | | | +| `» provisioner` | string | false | | | +| `» updated_at` | string(date-time) | false | | | +| `» workspace_owner_count` | integer | false | | | #### Enumerated Values @@ -1542,61 +1613,61 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/d Status Code **200** -| Name | Type | Required | Restrictions | Description | -| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `[array item]` | array | false | | | -| `» agents` | array | false | | | -| `»» apps` | array | false | | | -| `»»» command` | string | false | | | -| `»»» display_name` | string | false | | DisplayName is a friendly name for the app. | -| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on
the client or not. | -| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | -| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | -| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | -| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | -| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. | -| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `»»» id` | string(uuid) | false | | | -| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | -| `»»» slug` | string | false | | Slug is a unique identifier within the agent. | -| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | -| `»»» url` | string | false | | URL is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | -| `»» architecture` | string | false | | | -| `»» connection_timeout_seconds` | integer | false | | | -| `»» created_at` | string(date-time) | false | | | -| `»» directory` | string | false | | | -| `»» disconnected_at` | string(date-time) | false | | | -| `»» environment_variables` | object | false | | | -| `»»» [any property]` | string | false | | | -| `»» first_connected_at` | string(date-time) | false | | | -| `»» id` | string(uuid) | false | | | -| `»» instance_id` | string | false | | | -| `»» last_connected_at` | string(date-time) | false | | | -| `»» latency` | object | false | | DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). | -| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | -| `»»»» latency_ms` | number | false | | | -| `»»»» preferred` | boolean | false | | | -| `»» name` | string | false | | | -| `»» operating_system` | string | false | | | -| `»» resource_id` | string(uuid) | false | | | -| `»» startup_script` | string | false | | | -| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | -| `»» troubleshooting_url` | string | false | | | -| `»» updated_at` | string(date-time) | false | | | -| `»» version` | string | false | | | -| `» created_at` | string(date-time) | false | | | -| `» daily_cost` | integer | false | | | -| `» hide` | boolean | false | | | -| `» icon` | string | false | | | -| `» id` | string(uuid) | false | | | -| `» job_id` | string(uuid) | false | | | -| `» metadata` | array | false | | | -| `»» key` | string | false | | | -| `»» sensitive` | boolean | false | | | -| `»» value` | string | false | | | -| `» name` | string | false | | | -| `» type` | string | false | | | -| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[array item]` | array | false | | | +| `» agents` | array | false | | | +| `»» apps` | array | false | | | +| `»»» command` | string | false | | | +| `»»» display_name` | string | false | | »»display name is a friendly name for the app. | +| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. | +| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | +| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | +| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | +| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | +| `»»»» url` | string | false | | »»»url specifies the endpoint to check for the app health. | +| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | +| `»»» id` | string(uuid) | false | | | +| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | +| `»»» slug` | string | false | | Slug is a unique identifier within the agent. | +| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. | +| `»»» url` | string | false | | »»url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | +| `»» architecture` | string | false | | | +| `»» connection_timeout_seconds` | integer | false | | | +| `»» created_at` | string(date-time) | false | | | +| `»» directory` | string | false | | | +| `»» disconnected_at` | string(date-time) | false | | | +| `»» environment_variables` | object | false | | | +| `»»» [any property]` | string | false | | | +| `»» first_connected_at` | string(date-time) | false | | | +| `»» id` | string(uuid) | false | | | +| `»» instance_id` | string | false | | | +| `»» last_connected_at` | string(date-time) | false | | | +| `»» latency` | object | false | | »latency is mapped by region name (e.g. "New York City", "Seattle"). | +| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | +| `»»»» latency_ms` | number | false | | | +| `»»»» preferred` | boolean | false | | | +| `»» name` | string | false | | | +| `»» operating_system` | string | false | | | +| `»» resource_id` | string(uuid) | false | | | +| `»» startup_script` | string | false | | | +| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | +| `»» troubleshooting_url` | string | false | | | +| `»» updated_at` | string(date-time) | false | | | +| `»» version` | string | false | | | +| `» created_at` | string(date-time) | false | | | +| `» daily_cost` | integer | false | | | +| `» hide` | boolean | false | | | +| `» icon` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» job_id` | string(uuid) | false | | | +| `» metadata` | array | false | | | +| `»» key` | string | false | | | +| `»» sensitive` | boolean | false | | | +| `»» value` | string | false | | | +| `» name` | string | false | | | +| `» type` | string | false | | | +| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | #### Enumerated Values @@ -1883,61 +1954,61 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/r Status Code **200** -| Name | Type | Required | Restrictions | Description | -| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `[array item]` | array | false | | | -| `» agents` | array | false | | | -| `»» apps` | array | false | | | -| `»»» command` | string | false | | | -| `»»» display_name` | string | false | | DisplayName is a friendly name for the app. | -| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on
the client or not. | -| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | -| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | -| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | -| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | -| `»»»» url` | string | false | | URL specifies the endpoint to check for the app health. | -| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies
an icon to be displayed in the dashboard. | -| `»»» id` | string(uuid) | false | | | -| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | -| `»»» slug` | string | false | | Slug is a unique identifier within the agent. | -| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the
`coder server` or via a hostname-based dev URL. If this is set to true
and there is no app wildcard configured on the server, the app will not
be accessible in the UI. | -| `»»» url` | string | false | | URL is the address being proxied to inside the workspace.
If external is specified, this will be opened on the client. | -| `»» architecture` | string | false | | | -| `»» connection_timeout_seconds` | integer | false | | | -| `»» created_at` | string(date-time) | false | | | -| `»» directory` | string | false | | | -| `»» disconnected_at` | string(date-time) | false | | | -| `»» environment_variables` | object | false | | | -| `»»» [any property]` | string | false | | | -| `»» first_connected_at` | string(date-time) | false | | | -| `»» id` | string(uuid) | false | | | -| `»» instance_id` | string | false | | | -| `»» last_connected_at` | string(date-time) | false | | | -| `»» latency` | object | false | | DERPLatency is mapped by region name (e.g. "New York City", "Seattle"). | -| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | -| `»»»» latency_ms` | number | false | | | -| `»»»» preferred` | boolean | false | | | -| `»» name` | string | false | | | -| `»» operating_system` | string | false | | | -| `»» resource_id` | string(uuid) | false | | | -| `»» startup_script` | string | false | | | -| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | -| `»» troubleshooting_url` | string | false | | | -| `»» updated_at` | string(date-time) | false | | | -| `»» version` | string | false | | | -| `» created_at` | string(date-time) | false | | | -| `» daily_cost` | integer | false | | | -| `» hide` | boolean | false | | | -| `» icon` | string | false | | | -| `» id` | string(uuid) | false | | | -| `» job_id` | string(uuid) | false | | | -| `» metadata` | array | false | | | -| `»» key` | string | false | | | -| `»» sensitive` | boolean | false | | | -| `»» value` | string | false | | | -| `» name` | string | false | | | -| `» type` | string | false | | | -| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[array item]` | array | false | | | +| `» agents` | array | false | | | +| `»» apps` | array | false | | | +| `»»» command` | string | false | | | +| `»»» display_name` | string | false | | »»display name is a friendly name for the app. | +| `»»» external` | boolean | false | | External specifies whether the URL should be opened externally on the client or not. | +| `»»» health` | [codersdk.WorkspaceAppHealth](schemas.md#codersdkworkspaceapphealth) | false | | | +| `»»» healthcheck` | [codersdk.Healthcheck](schemas.md#codersdkhealthcheck) | false | | Healthcheck specifies the configuration for checking app health. | +| `»»»» interval` | integer | false | | Interval specifies the seconds between each health check. | +| `»»»» threshold` | integer | false | | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". | +| `»»»» url` | string | false | | »»»url specifies the endpoint to check for the app health. | +| `»»» icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. | +| `»»» id` | string(uuid) | false | | | +| `»»» sharing_level` | [codersdk.WorkspaceAppSharingLevel](schemas.md#codersdkworkspaceappsharinglevel) | false | | | +| `»»» slug` | string | false | | Slug is a unique identifier within the agent. | +| `»»» subdomain` | boolean | false | | Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI. | +| `»»» url` | string | false | | »»url is the address being proxied to inside the workspace. If external is specified, this will be opened on the client. | +| `»» architecture` | string | false | | | +| `»» connection_timeout_seconds` | integer | false | | | +| `»» created_at` | string(date-time) | false | | | +| `»» directory` | string | false | | | +| `»» disconnected_at` | string(date-time) | false | | | +| `»» environment_variables` | object | false | | | +| `»»» [any property]` | string | false | | | +| `»» first_connected_at` | string(date-time) | false | | | +| `»» id` | string(uuid) | false | | | +| `»» instance_id` | string | false | | | +| `»» last_connected_at` | string(date-time) | false | | | +| `»» latency` | object | false | | »latency is mapped by region name (e.g. "New York City", "Seattle"). | +| `»»» [any property]` | [codersdk.DERPRegion](schemas.md#codersdkderpregion) | false | | | +| `»»»» latency_ms` | number | false | | | +| `»»»» preferred` | boolean | false | | | +| `»» name` | string | false | | | +| `»» operating_system` | string | false | | | +| `»» resource_id` | string(uuid) | false | | | +| `»» startup_script` | string | false | | | +| `»» status` | [codersdk.WorkspaceAgentStatus](schemas.md#codersdkworkspaceagentstatus) | false | | | +| `»» troubleshooting_url` | string | false | | | +| `»» updated_at` | string(date-time) | false | | | +| `»» version` | string | false | | | +| `» created_at` | string(date-time) | false | | | +| `» daily_cost` | integer | false | | | +| `» hide` | boolean | false | | | +| `» icon` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» job_id` | string(uuid) | false | | | +| `» metadata` | array | false | | | +| `»» key` | string | false | | | +| `»» sensitive` | boolean | false | | | +| `»» value` | string | false | | | +| `» name` | string | false | | | +| `» type` | string | false | | | +| `» workspace_transition` | [codersdk.WorkspaceTransition](schemas.md#codersdkworkspacetransition) | false | | | #### Enumerated Values @@ -2017,26 +2088,26 @@ curl -X GET http://coder-server:8080/api/v2/templateversions/{templateversion}/s Status Code **200** -| Name | Type | Required | Restrictions | Description | -| ------------------------------ | ------------------------------------------------------------------------------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `[array item]` | array | false | | | -| `» allow_override_destination` | boolean | false | | | -| `» allow_override_source` | boolean | false | | | -| `» created_at` | string(date-time) | false | | | -| `» default_destination_scheme` | [codersdk.ParameterDestinationScheme](schemas.md#codersdkparameterdestinationscheme) | false | | | -| `» default_refresh` | string | false | | | -| `» default_source_scheme` | [codersdk.ParameterSourceScheme](schemas.md#codersdkparametersourcescheme) | false | | | -| `» default_source_value` | string | false | | | -| `» description` | string | false | | | -| `» id` | string(uuid) | false | | | -| `» job_id` | string(uuid) | false | | | -| `» name` | string | false | | | -| `» redisplay_value` | boolean | false | | | -| `» validation_condition` | string | false | | | -| `» validation_contains` | array | false | | This is a special array of items provided if the validation condition
explicitly states the value must be one of a set. | -| `» validation_error` | string | false | | | -| `» validation_type_system` | string | false | | | -| `» validation_value_type` | string | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------------------ | ------------------------------------------------------------------------------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `[array item]` | array | false | | | +| `» allow_override_destination` | boolean | false | | | +| `» allow_override_source` | boolean | false | | | +| `» created_at` | string(date-time) | false | | | +| `» default_destination_scheme` | [codersdk.ParameterDestinationScheme](schemas.md#codersdkparameterdestinationscheme) | false | | | +| `» default_refresh` | string | false | | | +| `» default_source_scheme` | [codersdk.ParameterSourceScheme](schemas.md#codersdkparametersourcescheme) | false | | | +| `» default_source_value` | string | false | | | +| `» description` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» job_id` | string(uuid) | false | | | +| `» name` | string | false | | | +| `» redisplay_value` | boolean | false | | | +| `» validation_condition` | string | false | | | +| `» validation_contains` | array | false | | This is a special array of items provided if the validation condition explicitly states the value must be one of a set. | +| `» validation_error` | string | false | | | +| `» validation_type_system` | string | false | | | +| `» validation_value_type` | string | false | | | #### Enumerated Values diff --git a/docs/api/users.md b/docs/api/users.md index 8531673ba4..a01027eea6 100644 --- a/docs/api/users.md +++ b/docs/api/users.md @@ -587,18 +587,18 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/keys/tokens \ Status Code **200** -| Name | Type | Required | Restrictions | Description | -| -------------------- | ------------------------------------------------------ | -------- | ------------ | ----------------------------------------- | -| `[array item]` | array | false | | | -| `» created_at` | string(date-time) | true | | | -| `» expires_at` | string(date-time) | true | | | -| `» id` | string | true | | | -| `» last_used` | string(date-time) | true | | | -| `» lifetime_seconds` | integer | true | | | -| `» login_type` | [codersdk.LoginType](schemas.md#codersdklogintype) | true | | | -| `» scope` | [codersdk.APIKeyScope](schemas.md#codersdkapikeyscope) | true | | | -| `» updated_at` | string(date-time) | true | | | -| `» user_id` | string(uuid) | true | | NOTE: do not ever return the HashedSecret | +| Name | Type | Required | Restrictions | Description | +| -------------------- | ------------------------------------------------------ | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» created_at` | string(date-time) | true | | | +| `» expires_at` | string(date-time) | true | | | +| `» id` | string | true | | | +| `» last_used` | string(date-time) | true | | | +| `» lifetime_seconds` | integer | true | | | +| `» login_type` | [codersdk.LoginType](schemas.md#codersdklogintype) | true | | | +| `» scope` | [codersdk.APIKeyScope](schemas.md#codersdkapikeyscope) | true | | | +| `» updated_at` | string(date-time) | true | | | +| `» user_id` | string(uuid) | true | | | #### Enumerated Values diff --git a/docs/manifest.json b/docs/manifest.json index d0b0d78417..f480e8f0e8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -325,14 +325,14 @@ "path": "./api/index.md", "icon_path": "./images/icons/api.svg", "children": [ - { - "title": "Authentication", - "path": "./api/authentication.md" - }, { "title": "General", "path": "./api/general.md" }, + { + "title": "Agents", + "path": "./api/agents.md" + }, { "title": "Applications", "path": "./api/applications.md" @@ -341,49 +341,53 @@ "title": "Audit", "path": "./api/audit.md" }, + { + "title": "Authentication", + "path": "./api/authentication.md" + }, { "title": "Authorization", "path": "./api/authorization.md" }, - { - "title": "Files", - "path": "./api/files.md" - }, - { - "title": "Organizations", - "path": "./api/organizations.md" - }, - { - "title": "Members", - "path": "./api/members.md" - }, - { - "title": "Workspaces", - "path": "./api/workspaces.md" - }, - { - "title": "Templates", - "path": "./api/templates.md" - }, - { - "title": "Parameters", - "path": "./api/parameters.md" - }, - { - "title": "Users", - "path": "./api/users.md" - }, { "title": "Builds", "path": "./api/builds.md" }, { - "title": "Agents", - "path": "./api/agents.md" + "title": "Enterprise", + "path": "./api/enterprise.md" + }, + { + "title": "Files", + "path": "./api/files.md" + }, + { + "title": "Members", + "path": "./api/members.md" + }, + { + "title": "Organizations", + "path": "./api/organizations.md" + }, + { + "title": "Parameters", + "path": "./api/parameters.md" }, { "title": "Schemas", "path": "./api/schemas.md" + }, + { + "title": "Templates", + "path": "./api/templates.md" + }, + { + "title": "Users", + "path": "./api/users.md" + }, + { + "title": "Workspaces", + "path": "./api/workspaces.md" } ] } diff --git a/enterprise/coderd/appearance.go b/enterprise/coderd/appearance.go index ab7a9cde1b..fef1c2ff5e 100644 --- a/enterprise/coderd/appearance.go +++ b/enterprise/coderd/appearance.go @@ -15,6 +15,13 @@ import ( "github.com/coder/coder/codersdk" ) +// @Summary Get appearance +// @ID get-appearance +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Success 200 {object} codersdk.AppearanceConfig +// @Router /appearance [get] func (api *API) appearance(rw http.ResponseWriter, r *http.Request) { api.entitlementsMu.RLock() isEntitled := api.entitlements.Features[codersdk.FeatureAppearance].Entitlement == codersdk.EntitlementEntitled @@ -74,6 +81,14 @@ func validateHexColor(color string) error { return err } +// @Summary Update appearance +// @ID update-appearance +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param request body codersdk.AppearanceConfig true "Update appearance request" +// @Success 200 {object} codersdk.AppearanceConfig +// @Router /appearance [put] func (api *API) putAppearance(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() diff --git a/enterprise/coderd/coderd.go b/enterprise/coderd/coderd.go index 0ea4eff280..32184e43cd 100644 --- a/enterprise/coderd/coderd.go +++ b/enterprise/coderd/coderd.go @@ -81,7 +81,7 @@ func New(ctx context.Context, options *Options) (*API, error) { httpmw.ExtractOrganizationParam(api.Database), ) r.Post("/", api.postGroupByOrganization) - r.Get("/", api.groups) + r.Get("/", api.groupsByOrganization) r.Route("/{groupName}", func(r chi.Router) { r.Use( httpmw.ExtractGroupByNameParam(api.Database), @@ -331,6 +331,13 @@ func (api *API) updateEntitlements(ctx context.Context) error { return nil } +// @Summary Get entitlements +// @ID get-entitlements +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Success 200 {object} codersdk.Entitlements +// @Router /entitlements [get] func (api *API) serveEntitlements(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() api.entitlementsMu.RLock() diff --git a/enterprise/coderd/groups.go b/enterprise/coderd/groups.go index ec566c8569..ce0f92fc22 100644 --- a/enterprise/coderd/groups.go +++ b/enterprise/coderd/groups.go @@ -17,6 +17,16 @@ import ( "github.com/coder/coder/codersdk" ) +// @Summary Create group for organization +// @ID create-group-for-organization +// @Security CoderSessionToken +// @Accept json +// @Produce json +// @Tags Templates +// @Param request body codersdk.CreateGroupRequest true "Create group request" +// @Param organization path string true "Organization ID" +// @Success 201 {object} codersdk.Group +// @Router /organizations/{organization}/groups [post] func (api *API) postGroupByOrganization(rw http.ResponseWriter, r *http.Request) { var ( ctx = r.Context() @@ -264,6 +274,14 @@ func (api *API) deleteGroup(rw http.ResponseWriter, r *http.Request) { }) } +// @Summary Get group by name +// @ID get-group-by-name +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param groupName path string true "Group name" +// @Success 200 {object} codersdk.Group +// @Router /groups/{groupName} [get] func (api *API) group(rw http.ResponseWriter, r *http.Request) { var ( ctx = r.Context() @@ -284,6 +302,26 @@ func (api *API) group(rw http.ResponseWriter, r *http.Request) { httpapi.Write(ctx, rw, http.StatusOK, convertGroup(group, users)) } +// @Summary Get groups by organization +// @ID get-groups-by-organization +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param organization path string true "Organization ID" format(uuid) +// @Success 200 {array} codersdk.Group +// @Router /organizations/{organization}/groups [get] +func (api *API) groupsByOrganization(rw http.ResponseWriter, r *http.Request) { + api.groups(rw, r) +} + +// @Summary Get groups +// @ID get-groups +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param organization path string true "Organization ID" format(uuid) +// @Success 200 {array} codersdk.Group +// @Router /groups [get] func (api *API) groups(rw http.ResponseWriter, r *http.Request) { var ( ctx = r.Context() diff --git a/enterprise/coderd/licenses.go b/enterprise/coderd/licenses.go index 28a732e2b8..0ef3a564f9 100644 --- a/enterprise/coderd/licenses.go +++ b/enterprise/coderd/licenses.go @@ -48,6 +48,15 @@ var Keys = map[string]ed25519.PublicKey{"2022-08-12": ed25519.PublicKey(key20220 // we generally don't want the old features to immediately break without warning. With a grace // period on the license, features will continue to work from the old license until its grace // period, then the users will get a warning allowing them to gracefully stop using the feature. +// +// @Summary Add new license +// @ID add-new-license +// @Security CoderSessionToken +// @Produce json +// @Tags Organizations +// @Param request body codersdk.AddLicenseRequest true "Add license request" +// @Success 201 {object} codersdk.License +// @Router /licenses [post] func (api *API) postLicense(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() if !api.AGPL.Authorize(r, rbac.ActionCreate, rbac.ResourceLicense) { @@ -121,6 +130,13 @@ func (api *API) postLicense(rw http.ResponseWriter, r *http.Request) { httpapi.Write(ctx, rw, http.StatusCreated, convertLicense(dl, rawClaims)) } +// @Summary Get licenses +// @ID get-licenses +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Success 200 {array} codersdk.License +// @Router /licenses [get] func (api *API) licenses(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() licenses, err := api.Database.GetLicenses(ctx) @@ -155,6 +171,14 @@ func (api *API) licenses(rw http.ResponseWriter, r *http.Request) { httpapi.Write(ctx, rw, http.StatusOK, sdkLicenses) } +// @Summary Delete license +// @ID delete-license +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param id path string true "License ID" format(number) +// @Success 200 +// @Router /license/{id} [delete] func (api *API) deleteLicense(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() if !api.AGPL.Authorize(r, rbac.ActionDelete, rbac.ResourceLicense) { diff --git a/enterprise/coderd/provisionerdaemons.go b/enterprise/coderd/provisionerdaemons.go index d13c4ffdd1..d49a96ab13 100644 --- a/enterprise/coderd/provisionerdaemons.go +++ b/enterprise/coderd/provisionerdaemons.go @@ -45,6 +45,14 @@ func (api *API) provisionerDaemonsEnabledMW(next http.Handler) http.Handler { }) } +// @Summary Get provisioner daemons +// @ID get-provisioner-daemons +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param organization path string true "Organization ID" format(uuid) +// @Success 200 {array} codersdk.ProvisionerDaemon +// @Router /organizations/{organization}/provisionerdaemons [get] func (api *API) provisionerDaemons(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() org := httpmw.OrganizationParam(r) @@ -82,6 +90,15 @@ func (api *API) provisionerDaemons(rw http.ResponseWriter, r *http.Request) { } // Serves the provisioner daemon protobuf API over a WebSocket. +// +// @Summary Serve provisioner daemon +// @ID serve-provisioner-daemon +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param organization path string true "Organization ID" format(uuid) +// @Success 101 +// @Router /organizations/{organization}/provisionerdaemons/serve [get] func (api *API) provisionerDaemonServe(rw http.ResponseWriter, r *http.Request) { tags := map[string]string{} if r.URL.Query().Has("tag") { diff --git a/enterprise/coderd/replicas.go b/enterprise/coderd/replicas.go index 906597f257..b5c5af2743 100644 --- a/enterprise/coderd/replicas.go +++ b/enterprise/coderd/replicas.go @@ -10,6 +10,14 @@ import ( ) // replicas returns the number of replicas that are active in Coder. +// +// @Summary Get active replicas +// @ID get-active-replicas +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Success 200 {array} codersdk.Replica +// @Router /replicas [get] func (api *API) replicas(rw http.ResponseWriter, r *http.Request) { if !api.AGPL.Authorize(r, rbac.ActionRead, rbac.ResourceReplicas) { httpapi.ResourceNotFound(rw) diff --git a/enterprise/coderd/scim.go b/enterprise/coderd/scim.go index 7ee4a41a79..b72486fb28 100644 --- a/enterprise/coderd/scim.go +++ b/enterprise/coderd/scim.go @@ -43,6 +43,14 @@ func (api *API) scimVerifyAuthHeader(r *http.Request) bool { // Okta to try and create each user individually, this way we don't need to // implement fetching users twice. // +// @Summary SCIM 2.0: Get users +// @ID scim-get-users +// @Security CoderSessionToken +// @Produce application/scim+json +// @Tags Enterprise +// @Success 200 +// @Router /scim/v2/Users [post] +// //nolint:revive func (api *API) scimGetUsers(rw http.ResponseWriter, r *http.Request) { if !api.scimVerifyAuthHeader(r) { @@ -62,6 +70,19 @@ func (api *API) scimGetUsers(rw http.ResponseWriter, r *http.Request) { // This is done to always force Okta to try and create the user, this way we // don't need to implement fetching users twice. // +// scimGetUsers intentionally always returns no users. This is done to always force +// Okta to try and create each user individually, this way we don't need to +// implement fetching users twice. +// +// @Summary SCIM 2.0: Get user by ID +// @ID scim-get-user-by-id +// @Security CoderSessionToken +// @Produce application/scim+json +// @Tags Enterprise +// @Param id path string true "User ID" format(uuid) +// @Failure 404 +// @Router /scim/v2/Users/{id} [get] +// //nolint:revive func (api *API) scimGetUser(rw http.ResponseWriter, r *http.Request) { if !api.scimVerifyAuthHeader(r) { @@ -86,7 +107,7 @@ type SCIMUser struct { } `json:"name"` Emails []struct { Primary bool `json:"primary"` - Value string `json:"value"` + Value string `json:"value" format:"email"` Type string `json:"type"` Display string `json:"display"` } `json:"emails"` @@ -98,6 +119,15 @@ type SCIMUser struct { } // scimPostUser creates a new user, or returns the existing user if it exists. +// +// @Summary SCIM 2.0: Create new user +// @ID scim-create-new-user +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param request body coderd.SCIMUser true "New user" +// @Success 200 {object} coderd.SCIMUser +// @Router /scim/v2/Users [post] func (api *API) scimPostUser(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() if !api.scimVerifyAuthHeader(r) { @@ -144,6 +174,16 @@ func (api *API) scimPostUser(rw http.ResponseWriter, r *http.Request) { } // scimPatchUser supports suspending and activating users only. +// +// @Summary SCIM 2.0: Update user account +// @ID scim-update-user-status +// @Security CoderSessionToken +// @Produce application/scim+json +// @Tags Enterprise +// @Param id path string true "User ID" format(uuid) +// @Param request body coderd.SCIMUser true "Update user request" +// @Success 200 {object} codersdk.User +// @Router /scim/v2/Users/{id} [patch] func (api *API) scimPatchUser(rw http.ResponseWriter, r *http.Request) { ctx := r.Context() if !api.scimVerifyAuthHeader(r) { diff --git a/enterprise/coderd/scim_test.go b/enterprise/coderd/scim_test.go index 79fd0c533a..c0ebf1356d 100644 --- a/enterprise/coderd/scim_test.go +++ b/enterprise/coderd/scim_test.go @@ -34,7 +34,7 @@ func makeScimUser(t testing.TB) coderd.SCIMUser { }, Emails: []struct { Primary bool "json:\"primary\"" - Value string "json:\"value\"" + Value string "json:\"value\" format:\"email\"" Type string "json:\"type\"" Display string "json:\"display\"" }{ diff --git a/enterprise/coderd/templates.go b/enterprise/coderd/templates.go index 0e11261710..397101c51f 100644 --- a/enterprise/coderd/templates.go +++ b/enterprise/coderd/templates.go @@ -18,6 +18,14 @@ import ( "github.com/coder/coder/codersdk" ) +// @Summary Get template ACLs +// @ID get-template-acls +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param template path string true "Template ID" format(uuid) +// @Success 200 {array} codersdk.TemplateUser +// @Router /templates/{template}/acl [get] func (api *API) templateACL(rw http.ResponseWriter, r *http.Request) { var ( ctx = r.Context() @@ -92,6 +100,15 @@ func (api *API) templateACL(rw http.ResponseWriter, r *http.Request) { }) } +// @Summary Update template ACL +// @ID update-template-acl +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param template path string true "Template ID" format(uuid) +// @Param request body codersdk.UpdateTemplateACL true "Update template request" +// @Success 200 {object} codersdk.Response +// @Router /templates/{template}/acl [patch] func (api *API) patchTemplateACL(rw http.ResponseWriter, r *http.Request) { var ( ctx = r.Context() diff --git a/enterprise/coderd/workspacequota.go b/enterprise/coderd/workspacequota.go index 67d07d9193..0416324508 100644 --- a/enterprise/coderd/workspacequota.go +++ b/enterprise/coderd/workspacequota.go @@ -99,6 +99,14 @@ func (c *committer) CommitQuota( }, nil } +// @Summary Get workspace quota by user +// @ID get-workspace-quota-by-user +// @Security CoderSessionToken +// @Produce json +// @Tags Enterprise +// @Param user path string true "User ID, name, or me" +// @Success 200 {object} codersdk.WorkspaceQuota +// @Router /workspace-quota/{user} [get] func (api *API) workspaceQuota(rw http.ResponseWriter, r *http.Request) { user := httpmw.UserParam(r) diff --git a/scripts/apidocgen/generate.sh b/scripts/apidocgen/generate.sh index b13eb2bc26..4ea9a490c3 100755 --- a/scripts/apidocgen/generate.sh +++ b/scripts/apidocgen/generate.sh @@ -20,7 +20,7 @@ log "Use temporary file: ${API_MD_TMP_FILE}" pushd "${PROJECT_ROOT}" go run github.com/swaggo/swag/cmd/swag@v1.8.9 init \ --generalInfo="coderd.go" \ - --dir="./coderd,./codersdk" \ + --dir="./coderd,./codersdk,./enterprise/coderd" \ --output="./coderd/apidoc" \ --outputTypes="go,json" \ --parseDependency=true diff --git a/scripts/apidocgen/markdown-template/debug.def b/scripts/apidocgen/markdown-template/debug.def deleted file mode 100644 index 04fcf8f761..0000000000 --- a/scripts/apidocgen/markdown-template/debug.def +++ /dev/null @@ -1 +0,0 @@ -{{= data.utils.inspect(data) }} diff --git a/scripts/apidocgen/markdown-template/main.dot b/scripts/apidocgen/markdown-template/main.dot index a4fa2d6b03..16aace697c 100644 --- a/scripts/apidocgen/markdown-template/main.dot +++ b/scripts/apidocgen/markdown-template/main.dot @@ -53,12 +53,16 @@ const countUppercase = words[0].length - words[0].replace(/[A-Z]/g, '').length; if (countUppercase > 1) { - let displayName = p.displayName.replace(/» \*\*additionalProperties\*\*/g, "It"); + let displayName = p.displayName.replace(/» \*\*additionalProperties\*\*/g, "It").replace("» ", ""); displayName = displayName.charAt(0).toUpperCase() + displayName.replace(/_/g, " ").toLowerCase().slice(1); description = displayName + " " + words.slice(1).join(' '); } return correctLetterCase(description); } + + /* Export functions that are used by other template partials. */ + data.functions = {}; + data.functions.renderDescription = renderDescription; }} {{? data.api.components && data.api.components.securitySchemes }}{{#def.security}}{{?}} diff --git a/scripts/apidocgen/markdown-template/responses.def b/scripts/apidocgen/markdown-template/responses.def index 843c676594..117320d16e 100644 --- a/scripts/apidocgen/markdown-template/responses.def +++ b/scripts/apidocgen/markdown-template/responses.def @@ -98,7 +98,7 @@ Status Code **{{=response.status}}** {{?}} |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| -{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}| +{{~block.rows :p}}|`{{=renderDisplayName(p)}}`|{{=renderResponsePropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{=data.functions.renderDescription(p)}}| {{~}} {{~}} {{?}} diff --git a/scripts/apidocgen/postprocess/main.go b/scripts/apidocgen/postprocess/main.go index 2b747d07d1..bea72a66e4 100644 --- a/scripts/apidocgen/postprocess/main.go +++ b/scripts/apidocgen/postprocess/main.go @@ -9,6 +9,7 @@ import ( "os" "path" "regexp" + "sort" "strings" "golang.org/x/xerrors" @@ -132,6 +133,18 @@ func writeDocs(sections [][]byte) error { }) } + // Sort API pages + // The "General" section is expected to be always first. + sort.Slice(mdFiles, func(i, j int) bool { + if mdFiles[i].title == "General" { + return true // "General" < ... - sorted + } + if mdFiles[j].title == "General" { + return false // ... < "General" - not sorted + } + return sort.StringsAreSorted([]string{mdFiles[i].title, mdFiles[j].title}) + }) + // Update manifest.json type route struct { Title string `json:"title,omitempty"`