selfhosted
/
coder
mirror of https://github.com/coder/coder.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: applications and authorization (#5477) 

* docs: Applications

* WIP

* WIP

* WIP

* Fix: consume

* Fix: @Description

* Fix

* Fix: s/none//g

* Fix: godoc nice

* Fix: description

* Fix: It

* Fix: code sample trim empty line

* More fixes

* Fix: br
This commit is contained in:
Marcin Tojek 2022-12-21 15:37:30 +01:00 committed by GitHub
parent 935bb99bed
commit 2bbeff53f9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 830 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
coderd/apidoc/docs.go
View File

@ -25,6 +25,97 @@ const docTemplate = `{
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/applications/auth-redirect": {
"get": {
"security": [
{
"CoderSessionToken": []
}
],
"tags": [
"Applications"
],
"summary": "Redirect to URI with encrypted API key",
"operationId": "redirect-to-uri-with-encrypted-api-key",
"parameters": [
{
"type": "string",
"description": "Redirect destination",
"name": "redirect_uri",
"in": "query"
}
],
"responses": {
"307": {
"description": "Temporary Redirect"
}
}
}
},
"/applications/host": {
"get": {
"security": [
{
"CoderSessionToken": []
}
],
"produces": [
"application/json"
],
"tags": [
"Applications"
],
"summary": "Get applications host",
"operationId": "get-app-host",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/codersdk.GetAppHostResponse"
}
}
}
}
},
"/authcheck": {
"post": {
"security": [
{
"CoderSessionToken": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Authorization"
],
"summary": "Check authorization",
"operationId": "check-authorization",
"parameters": [
{
"description": "Authorization request",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/codersdk.AuthorizationRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/codersdk.AuthorizationResponse"
}
}
}
}
},
"/organizations/{organization-id}/templates/": {
"post": {
"security": [
@ -32,6 +123,9 @@ const docTemplate = `{
"CoderSessionToken": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@ -427,6 +521,9 @@ const docTemplate = `{
"CoderSessionToken": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@ -468,6 +565,9 @@ const docTemplate = `{
"CoderSessionToken": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@ -509,6 +609,9 @@ const docTemplate = `{
"CoderSessionToken": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@ -553,6 +656,9 @@ const docTemplate = `{
"CoderSessionToken": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
@ -624,7 +730,67 @@ const docTemplate = `{
}
},
"definitions": {
"codersdk.AuthorizationCheck": {
"description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.",
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"create",
"read",
"update",
"delete"
]
},
"object": {
"description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.",
"$ref": "#/definitions/codersdk.AuthorizationObject"
}
}
},
"codersdk.AuthorizationObject": {
"description": "AuthorizationObject can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.",
"type": "object",
"properties": {
"organization_id": {
"description": "OrganizationID (optional) adds the set constraint to all resources owned by a given organization.",
"type": "string"
},
"owner_id": {
"description": "OwnerID (optional) adds the set constraint to all resources owned by a given user.",
"type": "string"
},
"resource_id": {
"description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the ` + "`" + `OwnerID` + "`" + ` and ` + "`" + `OrganizationID` + "`" + `\nif possible. Be as specific as possible using all the fields relevant.",
"type": "string"
},
"resource_type": {
"description": "ResourceType is the name of the resource.\n` + "`" + `./coderd/rbac/object.go` + "`" + ` has the list of valid resource types.",
"type": "string"
}
}
},
"codersdk.AuthorizationRequest": {
"type": "object",
"properties": {
"checks": {
"description": "Checks is a map keyed with an arbitrary string to a permission check.\nThe key can be any string that is helpful to the caller, and allows\nmultiple permission checks to be run in a single request.\nThe key ensures that each permission check has the same key in the\nresponse.",
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/codersdk.AuthorizationCheck"
}
}
}
},
"codersdk.AuthorizationResponse": {
"type": "object",
"additionalProperties": {
"type": "boolean"
}
},
"codersdk.CreateParameterRequest": {
"description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.",
"type": "object",
"required": [
"destination_scheme",
@ -712,6 +878,15 @@ const docTemplate = `{
}
}
},
"codersdk.GetAppHostResponse": {
"type": "object",
"properties": {
"host": {
"description": "Host is the externally accessible URL for the Coder instance.",
"type": "string"
}
}
},
"codersdk.Healthcheck": {
"type": "object",
"properties": {

148
coderd/apidoc/swagger.json
View File

@ -17,6 +17,85 @@
},
"basePath": "/api/v2",
"paths": {
"/applications/auth-redirect": {
"get": {
"security": [
{
"CoderSessionToken": []
}
],
"tags": ["Applications"],
"summary": "Redirect to URI with encrypted API key",
"operationId": "redirect-to-uri-with-encrypted-api-key",
"parameters": [
{
"type": "string",
"description": "Redirect destination",
"name": "redirect_uri",
"in": "query"
}
],
"responses": {
"307": {
"description": "Temporary Redirect"
}
}
}
},
"/applications/host": {
"get": {
"security": [
{
"CoderSessionToken": []
}
],
"produces": ["application/json"],
"tags": ["Applications"],
"summary": "Get applications host",
"operationId": "get-app-host",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/codersdk.GetAppHostResponse"
}
}
}
}
},
"/authcheck": {
"post": {
"security": [
{
"CoderSessionToken": []
}
],
"consumes": ["application/json"],
"produces": ["application/json"],
"tags": ["Authorization"],
"summary": "Check authorization",
"operationId": "check-authorization",
"parameters": [
{
"description": "Authorization request",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/codersdk.AuthorizationRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/codersdk.AuthorizationResponse"
}
}
}
}
},
"/organizations/{organization-id}/templates/": {
"post": {
"security": [
@ -24,6 +103,7 @@
"CoderSessionToken": []
}
],
"consumes": ["application/json"],
"produces": ["application/json"],
"tags": ["Templates"],
"summary": "Create template by organization",
@ -378,6 +458,7 @@
"CoderSessionToken": []
}
],
"consumes": ["application/json"],
"produces": ["application/json"],
"tags": ["Workspaces"],
"summary": "Update workspace metadata by ID",
@ -415,6 +496,7 @@
"CoderSessionToken": []
}
],
"consumes": ["application/json"],
"produces": ["application/json"],
"tags": ["Workspaces"],
"summary": "Update workspace autostart schedule by ID",
@ -452,6 +534,7 @@
"CoderSessionToken": []
}
],
"consumes": ["application/json"],
"produces": ["application/json"],
"tags": ["Workspaces"],
"summary": "Extend workspace deadline by ID",
@ -492,6 +575,7 @@
"CoderSessionToken": []
}
],
"consumes": ["application/json"],
"produces": ["application/json"],
"tags": ["Workspaces"],
"summary": "Update workspace TTL by ID",
@ -555,7 +639,62 @@
}
},
"definitions": {
"codersdk.AuthorizationCheck": {
"description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.",
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["create", "read", "update", "delete"]
},
"object": {
"description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.",
"$ref": "#/definitions/codersdk.AuthorizationObject"
}
}
},
"codersdk.AuthorizationObject": {
"description": "AuthorizationObject can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.",
"type": "object",
"properties": {
"organization_id": {
"description": "OrganizationID (optional) adds the set constraint to all resources owned by a given organization.",
"type": "string"
},
"owner_id": {
"description": "OwnerID (optional) adds the set constraint to all resources owned by a given user.",
"type": "string"
},
"resource_id": {
"description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the `OwnerID` and `OrganizationID`\nif possible. Be as specific as possible using all the fields relevant.",
"type": "string"
},
"resource_type": {
"description": "ResourceType is the name of the resource.\n`./coderd/rbac/object.go` has the list of valid resource types.",
"type": "string"
}
}
},
"codersdk.AuthorizationRequest": {
"type": "object",
"properties": {
"checks": {
"description": "Checks is a map keyed with an arbitrary string to a permission check.\nThe key can be any string that is helpful to the caller, and allows\nmultiple permission checks to be run in a single request.\nThe key ensures that each permission check has the same key in the\nresponse.",
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/codersdk.AuthorizationCheck"
}
}
}
},
"codersdk.AuthorizationResponse": {
"type": "object",
"additionalProperties": {
"type": "boolean"
}
},
"codersdk.CreateParameterRequest": {
"description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.",
"type": "object",
"required": [
"destination_scheme",
@ -635,6 +774,15 @@
}
}
},
"codersdk.GetAppHostResponse": {
"type": "object",
"properties": {
"host": {
"description": "Host is the externally accessible URL for the Coder instance.",
"type": "string"
}
}
},
"codersdk.Healthcheck": {
"type": "object",
"properties": {

10
coderd/authorize.go
View File

@ -106,6 +106,16 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action,
// checkAuthorization returns if the current API key can use the given
// permissions, factoring in the current user's roles and the API key scopes.
//
// @Summary Check authorization
// @ID check-authorization
// @Security CoderSessionToken
// @Accept json
// @Produce json
// @Tags Authorization
// @Param request body codersdk.AuthorizationRequest true "Authorization request"
// @Success 200 {object} codersdk.AuthorizationResponse
// @Router /authcheck [post]
func (api *API) checkAuthorization(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
auth := httpmw.UserAuthorization(r)

2
coderd/templates.go
View File

@ -145,7 +145,7 @@ func (api *API) deleteTemplate(rw http.ResponseWriter, r *http.Request) {
// @Summary Create template by organization
// @ID create-template-by-organization
// @Security CoderSessionToken
// @Consume json
// @Accept json
// @Produce json
// @Tags Templates
// @Param request body codersdk.CreateTemplateRequest true "Request body"

15
coderd/workspaceapps.go
View File

@ -65,6 +65,13 @@ var nonCanonicalHeaders = map[string]string{
"Sec-Websocket-Version": "Sec-WebSocket-Version",
}
// @Summary Get applications host
// @ID get-app-host
// @Security CoderSessionToken
// @Produce json
// @Tags Applications
// @Success 200 {object} codersdk.GetAppHostResponse
// @Router /applications/host [get]
func (api *API) appHost(rw http.ResponseWriter, r *http.Request) {
host := api.AppHostname
if host != "" && api.AccessURL.Port() != "" {
@ -607,6 +614,14 @@ func (api *API) setWorkspaceAppCookie(rw http.ResponseWriter, r *http.Request, t
return true
}
// @Summary Redirect to URI with encrypted API key
// @ID redirect-to-uri-with-encrypted-api-key
// @Security CoderSessionToken
// @Tags Applications
// @Param redirect_uri query string false "Redirect destination"
// @Success 307
// @Router /applications/auth-redirect [get]
//
// workspaceApplicationAuth is an endpoint on the main router that handles
// redirects from the subdomain handler.
//

8
coderd/workspaces.go
View File

@ -564,7 +564,7 @@ func (api *API) postWorkspacesByOrganization(rw http.ResponseWriter, r *http.Req
// @Summary Update workspace metadata by ID
// @ID update-workspace-metadata-by-id
// @Security CoderSessionToken
// @Consume json
// @Accept json
// @Produce json
// @Tags Workspaces
// @Param workspace path string true "Workspace ID" format(uuid)
@ -654,7 +654,7 @@ func (api *API) patchWorkspace(rw http.ResponseWriter, r *http.Request) {
// @Summary Update workspace autostart schedule by ID
// @ID update-workspace-autostart-schedule-by-id
// @Security CoderSessionToken
// @Consume json
// @Accept json
// @Produce json
// @Tags Workspaces
// @Param workspace path string true "Workspace ID" format(uuid)
@ -717,7 +717,7 @@ func (api *API) putWorkspaceAutostart(rw http.ResponseWriter, r *http.Request) {
// @Summary Update workspace TTL by ID
// @ID update-workspace-ttl-by-id
// @Security CoderSessionToken
// @Consume json
// @Accept json
// @Produce json
// @Tags Workspaces
// @Param workspace path string true "Workspace ID" format(uuid)
@ -793,7 +793,7 @@ func (api *API) putWorkspaceTTL(rw http.ResponseWriter, r *http.Request) {
// @Summary Extend workspace deadline by ID
// @ID extend-workspace-deadline-by-id
// @Security CoderSessionToken
// @Consume json
// @Accept json
// @Produce json
// @Tags Workspaces
// @Param workspace path string true "Workspace ID" format(uuid)

25
codersdk/authorization.go
View File

@ -10,7 +10,7 @@ type AuthorizationResponse map[string]bool
// AuthorizationRequest is a structure instead of a map because
// go-playground/validate can only validate structs. If you attempt to pass
// a map into 'httpapi.Read', you will get an invalid type error.
// a map into `httpapi.Read`, you will get an invalid type error.
type AuthorizationRequest struct {
// Checks is a map keyed with an arbitrary string to a permission check.
// The key can be any string that is helpful to the caller, and allows
@ -20,8 +20,9 @@ type AuthorizationRequest struct {
Checks map[string]AuthorizationCheck `json:"checks"`
}
// AuthorizationCheck is used to check if the currently authenticated user (or
// the specified user) can do a given action to a given set of objects.
// AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.
//
// @Description AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.
type AuthorizationCheck struct {
// Object can represent a "set" of objects, such as:
// - All workspaces in an organization
@ -34,24 +35,26 @@ type AuthorizationCheck struct {
// Omitting the 'OrganizationID' could produce the incorrect value, as
// workspaces have both `user` and `organization` owners.
Object AuthorizationObject `json:"object"`
// Action can be 'create', 'read', 'update', or 'delete'
Action string `json:"action"`
Action string `json:"action" enums:"create,read,update,delete"`
}
// AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me,
// all workspaces across the entire product.
//
// @Description AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me,
// @Description all workspaces across the entire product.
type AuthorizationObject struct {
// ResourceType is the name of the resource.
// './coderd/rbac/object.go' has the list of valid resource types.
// `./coderd/rbac/object.go` has the list of valid resource types.
ResourceType string `json:"resource_type"`
// OwnerID (optional) is a user_id. It adds the set constraint to all resources owned
// by a given user.
// OwnerID (optional) adds the set constraint to all resources owned by a given user.
OwnerID string `json:"owner_id,omitempty"`
// OrganizationID (optional) is an organization_id. It adds the set constraint to
// all resources owned by a given organization.
// OrganizationID (optional) adds the set constraint to all resources owned by a given organization.
OrganizationID string `json:"organization_id,omitempty"`
// ResourceID (optional) reduces the set to a singular resource. This assigns
// a resource ID to the resource type, eg: a single workspace.
// The rbac library will not fetch the resource from the database, so if you
// are using this option, you should also set the 'OwnerID' and 'OrganizationID'
// are using this option, you should also set the `OwnerID` and `OrganizationID`
// if possible. Be as specific as possible using all the fields relevant.
ResourceID string `json:"resource_id,omitempty"`
}

4
codersdk/parameters.go
View File

@ -83,7 +83,9 @@ type ParameterSchema struct {
ValidationContains []string `json:"validation_contains,omitempty"`
}
// CreateParameterRequest is used to create a new parameter value for a scope.
// CreateParameterRequest is a structure used to create a new parameter value for a scope.
//
// @Description CreateParameterRequest is a structure used to create a new parameter value for a scope.
type CreateParameterRequest struct {
// CloneID allows copying the value of another parameter.
// The other param must be related to the same template_id for this to

1
codersdk/workspaces.go
View File

@ -350,6 +350,7 @@ func (c *Client) WorkspaceByOwnerAndName(ctx context.Context, owner string, name
}
type GetAppHostResponse struct {
// Host is the externally accessible URL for the Coder instance.
Host string `json:"host"`
}

60
docs/api/applications.md Normal file
View File

@ -0,0 +1,60 @@
# Applications
> This page is incomplete, stay tuned.
## Redirect to URI with encrypted API key
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/applications/auth-redirect \
-H 'Coder-Session-Token: API_KEY'
```
`GET /applications/auth-redirect`
### Parameters
| Name | In | Type | Required | Description |
| ------------ | ----- | ------ | -------- | -------------------- |
| redirect_uri | query | string | false | Redirect destination |
### Responses
| Status | Meaning | Description | Schema |
| ------ | ----------------------------------------------------------------------- | ------------------ | ------ |
| 307 | [Temporary Redirect](https://tools.ietf.org/html/rfc7231#section-6.4.7) | Temporary Redirect | |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
## Get applications host
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/applications/host \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /applications/host`
### Example responses
> 200 Response
```json
{
"host": "string"
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.GetAppHostResponse](schemas.md#codersdkgetapphostresponse) |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.

69
docs/api/authorization.md Normal file
View File

@ -0,0 +1,69 @@
# Authorization
> This page is incomplete, stay tuned.
## Check authorization
### Code samples
```shell
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/authcheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /authcheck`
> Body parameter
```json
{
"checks": {
"property1": {
"action": "create",
"object": {
"organization_id": "string",
"owner_id": "string",
"resource_id": "string",
"resource_type": "string"
}
},
"property2": {
"action": "create",
"object": {
"organization_id": "string",
"owner_id": "string",
"resource_id": "string",
"resource_type": "string"
}
}
}
}
```
### Parameters
| Name | In | Type | Required | Description |
| ---- | ---- | ------------------------------------------------------------------------ | -------- | --------------------- |
| body | body | [codersdk.AuthorizationRequest](schemas.md#codersdkauthorizationrequest) | true | Authorization request |
### Example responses
> 200 Response
```json
{
"property1": true,
"property2": true
}
```
### Responses
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.AuthorizationResponse](schemas.md#codersdkauthorizationresponse) |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.

420
docs/api/schemas.md
View File

@ -2,6 +2,109 @@
> This page is incomplete, stay tuned.
## codersdk.AuthorizationCheck
```json
{
"action": "create",
"object": {
"organization_id": "string",
"owner_id": "string",
"resource_id": "string",
"resource_type": "string"
}
}
```
AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.
### Properties
| Name | Type | Required | Restrictions | Description |
| -------- | ------------------------------------------------------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | string | false | | |
| `object` | [codersdk.AuthorizationObject](#codersdkauthorizationobject) | false | | Object can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product. |
#### Enumerated Values
| Property | Value |
| -------- | ------ |
| action | create |
| action | read |
| action | update |
| action | delete |
## codersdk.AuthorizationObject
```json
{
"organization_id": "string",
"owner_id": "string",
"resource_id": "string",
"resource_type": "string"
}
```
AuthorizationObject can represent a "set" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.
### Properties
| Name | Type | Required | Restrictions | Description |
| ----------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization_id` | string | false | | Organization id (optional) adds the set constraint to all resources owned by a given organization. |
| `owner_id` | string | false | | Owner id (optional) adds the set constraint to all resources owned by a given user. |
| `resource_id` | string | false | | Resource id (optional) reduces the set to a singular resource. This assigns a resource ID to the resource type, eg: a single workspace. The rbac library will not fetch the resource from the database, so if you are using this option, you should also set the `OwnerID` and `OrganizationID` if possible. Be as specific as possible using all the fields relevant. |
| `resource_type` | string | false | | Resource type is the name of the resource. `./coderd/rbac/object.go` has the list of valid resource types. |
## codersdk.AuthorizationRequest
```json
{
"checks": {
"property1": {
"action": "create",
"object": {
"organization_id": "string",
"owner_id": "string",
"resource_id": "string",
"resource_type": "string"
}
},
"property2": {
"action": "create",
"object": {
"organization_id": "string",
"owner_id": "string",
"resource_id": "string",
"resource_type": "string"
}
}
}
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------ | ---------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checks` | object | false | | Checks is a map keyed with an arbitrary string to a permission check. The key can be any string that is helpful to the caller, and allows multiple permission checks to be run in a single request. The key ensures that each permission check has the same key in the response. |
| » `[any property]` | [codersdk.AuthorizationCheck](#codersdkauthorizationcheck) | false | | It is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects. |
## codersdk.AuthorizationResponse
```json
{
"property1": true,
"property2": true
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ---------------- | ------- | -------- | ------------ | ----------- |
| `[any property]` | boolean | false | | |
## codersdk.CreateParameterRequest
```json
@ -14,15 +117,17 @@
}
```
CreateParameterRequest is a structure used to create a new parameter value for a scope.
### Properties
| Name | Type | Required | Restrictions | Description |
| --------------------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `copy_from_parameter` | string | false | none | Copy from parameter allows copying the value of another parameter.<br>The other param must be related to the same template_id for this to<br>succeed.<br>No other fields are required if using this, as all fields will be copied<br>from the other parameter. |
| `destination_scheme` | string | true | none | none |
| `name` | string | true | none | none |
| `source_scheme` | string | true | none | none |
| `source_value` | string | true | none | none |
| Name | Type | Required | Restrictions | Description |
| --------------------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `copy_from_parameter` | string | false | | Copy from parameter allows copying the value of another parameter. The other param must be related to the same template_id for this to succeed. No other fields are required if using this, as all fields will be copied from the other parameter. |
| `destination_scheme` | string | true | | |
| `name` | string | true | | |
| `source_scheme` | string | true | | |
| `source_value` | string | true | | |
#### Enumerated Values
@ -57,16 +162,17 @@
### Properties
| Name | Type | Required | Restrictions | Description |
| ---------------------------------- | --------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow_user_cancel_workspace_jobs` | boolean | false | none | Allow users to cancel in-progress workspace jobs.<br>\*bool as the default value is "true". |
| `default_ttl_ms` | integer | false | none | Default ttl ms allows optionally specifying the default TTL<br>for all workspaces created from this template. |
| `description` | string | false | none | Description is a description of what the template contains. It must be<br>less than 128 bytes. |
| `display_name` | string | false | none | Display name is the displayed name of the template. |
| `icon` | string | false | none | Icon is a relative path or external URL that specifies<br>an icon to be displayed in the dashboard. |
| `name` | string | true | none | Name is the name of the template. |
| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | none | none |
| `template_version_id` | string | true | none | Template version id is an in-progress or completed job to use as an initial version<br>of the template.<br><br>This is required on creation to enable a user-flow of validating a<br>template works. There is no reason the data-model cannot support empty<br>templates, but it doesn't make sense for users. |
| Name | Type | Required | Restrictions | Description |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
| `allow_user_cancel_workspace_jobs` | boolean | false | | Allow users to cancel in-progress workspace jobs. \*bool as the default value is "true". |
| `default_ttl_ms` | integer | false | | Default ttl ms allows optionally specifying the default TTL for all workspaces created from this template. |
| `description` | string | false | | Description is a description of what the template contains. It must be less than 128 bytes. |
| `display_name` | string | false | | Display name is the displayed name of the template. |
| `icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. |
| `name` | string | true | | Name is the name of the template. |
| `parameter_values` | array of [codersdk.CreateParameterRequest](#codersdkcreateparameterrequest) | false | | Parameter values is a structure used to create a new parameter value for a scope.] |
| `template_version_id` | string | true | | Template version id is an in-progress or completed job to use as an initial version of the template. |
| This is required on creation to enable a user-flow of validating a template works. There is no reason the data-model cannot support empty templates, but it doesn't make sense for users. |
## codersdk.DERPRegion
@ -81,8 +187,22 @@
| Name | Type | Required | Restrictions | Description |
| ------------ | ------- | -------- | ------------ | ----------- |
| `latency_ms` | number | false | none | none |
| `preferred` | boolean | false | none | none |
| `latency_ms` | number | false | | |
| `preferred` | boolean | false | | |
## codersdk.GetAppHostResponse
```json
{
"host": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| ------ | ------ | -------- | ------------ | ------------------------------------------------------------- |
| `host` | string | false | | Host is the externally accessible URL for the Coder instance. |
## codersdk.Healthcheck
@ -98,9 +218,9 @@
| Name | Type | Required | Restrictions | Description |
| ----------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `interval` | integer | false | none | Interval specifies the seconds between each health check. |
| `threshold` | integer | false | none | Threshold specifies the number of consecutive failed health checks before returning "unhealthy". |
| `url` | string | false | none | Url specifies the url to check for the 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 url to check for the app health. |
## codersdk.ProvisionerJob
@ -126,17 +246,17 @@
| Name | Type | Required | Restrictions | Description |
| ------------------ | ------ | -------- | ------------ | ----------- |
| `canceled_at` | string | false | none | none |
| `completed_at` | string | false | none | none |
| `created_at` | string | false | none | none |
| `error` | string | false | none | none |
| `file_id` | string | false | none | none |
| `id` | string | false | none | none |
| `started_at` | string | false | none | none |
| `status` | string | false | none | none |
| `tags` | object | false | none | none |
| » `[any property]` | string | false | none | none |
| `worker_id` | string | false | none | none |
| `canceled_at` | string | false | | |
| `completed_at` | string | false | | |
| `created_at` | string | false | | |
| `error` | string | false | | |
| `file_id` | string | false | | |
| `id` | string | false | | |
| `started_at` | string | false | | |
| `status` | string | false | | |
| `tags` | object | false | | |
| » `[any property]` | string | false | | |
| `worker_id` | string | false | | |
## codersdk.PutExtendWorkspaceRequest
@ -150,7 +270,7 @@
| Name | Type | Required | Restrictions | Description |
| ---------- | ------ | -------- | ------------ | ----------- |
| `deadline` | string | true | none | none |
| `deadline` | string | true | | |
## codersdk.Response
@ -169,11 +289,11 @@
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------- | ------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detail` | string | false | none | Detail is a debug message that provides further insight into why the<br>action failed. This information can be technical and a regular golang<br>err.Error() text.<br>- "database: too many open connections"<br>- "stat: too many open files" |
| `message` | string | false | none | Message is an actionable message that depicts actions the request took.<br>These messages should be fully formed sentences with proper punctuation.<br>Examples:<br>- "A user has been created."<br>- "Failed to create a user." |
| `validations` | array of [codersdk.ValidationError](#codersdkvalidationerror) | false | none | Validations are form field-specific friendly error messages. They will be<br>shown on a form field in the UI. These can also be used to add additional<br>context if there is a set of errors in the primary 'Message'. |
| Name | Type | Required | Restrictions | Description |
| ------------- | ------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detail` | string | false | | Detail is a debug message that provides further insight into why the action failed. This information can be technical and a regular golang err.Error() text. - "database: too many open connections" - "stat: too many open files" |
| `message` | string | false | | Message is an actionable message that depicts actions the request took. These messages should be fully formed sentences with proper punctuation. Examples: - "A user has been created." - "Failed to create a user." |
| `validations` | array of [codersdk.ValidationError](#codersdkvalidationerror) | false | | Validations are form field-specific friendly error messages. They will be shown on a form field in the UI. These can also be used to add additional context if there is a set of errors in the primary 'Message'. |
## codersdk.Template
@ -212,23 +332,23 @@
| Name | Type | Required | Restrictions | Description |
| ---------------------------------- | ------------------------------------------------------------------ | -------- | ------------ | -------------------------------------------- |
| `active_user_count` | integer | false | none | Active user count is set to -1 when loading. |
| `active_version_id` | string | false | none | none |
| `allow_user_cancel_workspace_jobs` | boolean | false | none | none |
| `build_time_stats` | [codersdk.TemplateBuildTimeStats](#codersdktemplatebuildtimestats) | false | none | none |
| `created_at` | string | false | none | none |
| `created_by_id` | string | false | none | none |
| `created_by_name` | string | false | none | none |
| `default_ttl_ms` | integer | false | none | none |
| `description` | string | false | none | none |
| `display_name` | string | false | none | none |
| `icon` | string | false | none | none |
| `id` | string | false | none | none |
| `name` | string | false | none | none |
| `organization_id` | string | false | none | none |
| `provisioner` | string | false | none | none |
| `updated_at` | string | false | none | none |
| `workspace_owner_count` | integer | false | none | none |
| `active_user_count` | integer | false | | Active user count is set to -1 when loading. |
| `active_version_id` | string | false | | |
| `allow_user_cancel_workspace_jobs` | boolean | false | | |
| `build_time_stats` | [codersdk.TemplateBuildTimeStats](#codersdktemplatebuildtimestats) | false | | |
| `created_at` | string | false | | |
| `created_by_id` | string | false | | |
| `created_by_name` | string | false | | |
| `default_ttl_ms` | integer | false | | |
| `description` | string | false | | |
| `display_name` | string | false | | |
| `icon` | string | false | | |
| `id` | string | false | | |
| `name` | string | false | | |
| `organization_id` | string | false | | |
| `provisioner` | string | false | | |
| `updated_at` | string | false | | |
| `workspace_owner_count` | integer | false | | |
## codersdk.TemplateBuildTimeStats
@ -249,7 +369,7 @@
| Name | Type | Required | Restrictions | Description |
| ---------------- | ---------------------------------------------------- | -------- | ------------ | ----------- |
| `[any property]` | [codersdk.TransitionStats](#codersdktransitionstats) | false | none | none |
| `[any property]` | [codersdk.TransitionStats](#codersdktransitionstats) | false | | |
## codersdk.TransitionStats
@ -264,8 +384,8 @@
| Name | Type | Required | Restrictions | Description |
| ----- | ------- | -------- | ------------ | ----------- |
| `p50` | integer | false | none | none |
| `p95` | integer | false | none | none |
| `p50` | integer | false | | |
| `p95` | integer | false | | |
## codersdk.UpdateWorkspaceAutostartRequest
@ -279,7 +399,7 @@
| Name | Type | Required | Restrictions | Description |
| ---------- | ------ | -------- | ------------ | ----------- |
| `schedule` | string | false | none | none |
| `schedule` | string | false | | |
## codersdk.UpdateWorkspaceRequest
@ -293,7 +413,7 @@
| Name | Type | Required | Restrictions | Description |
| ------ | ------ | -------- | ------------ | ----------- |
| `name` | string | false | none | none |
| `name` | string | false | | |
## codersdk.UpdateWorkspaceTTLRequest
@ -307,7 +427,7 @@
| Name | Type | Required | Restrictions | Description |
| -------- | ------- | -------- | ------------ | ----------- |
| `ttl_ms` | integer | false | none | none |
| `ttl_ms` | integer | false | | |
## codersdk.ValidationError
@ -322,8 +442,8 @@
| Name | Type | Required | Restrictions | Description |
| -------- | ------ | -------- | ------------ | ----------- |
| `detail` | string | true | none | none |
| `field` | string | true | none | none |
| `detail` | string | true | | |
| `field` | string | true | | |
## codersdk.Workspace
@ -462,22 +582,22 @@
| Name | Type | Required | Restrictions | Description |
| ------------------------------------------- | -------------------------------------------------- | -------- | ------------ | ----------- |
| `autostart_schedule` | string | false | none | none |
| `created_at` | string | false | none | none |
| `id` | string | false | none | none |
| `last_used_at` | string | false | none | none |
| `latest_build` | [codersdk.WorkspaceBuild](#codersdkworkspacebuild) | false | none | none |
| `name` | string | false | none | none |
| `outdated` | boolean | false | none | none |
| `owner_id` | string | false | none | none |
| `owner_name` | string | false | none | none |
| `template_allow_user_cancel_workspace_jobs` | boolean | false | none | none |
| `template_display_name` | string | false | none | none |
| `template_icon` | string | false | none | none |
| `template_id` | string | false | none | none |
| `template_name` | string | false | none | none |
| `ttl_ms` | integer | false | none | none |
| `updated_at` | string | false | none | none |
| `autostart_schedule` | string | false | | |
| `created_at` | string | false | | |
| `id` | string | false | | |
| `last_used_at` | string | false | | |
| `latest_build` | [codersdk.WorkspaceBuild](#codersdkworkspacebuild) | false | | |
| `name` | string | false | | |
| `outdated` | boolean | false | | |
| `owner_id` | string | false | | |
| `owner_name` | string | false | | |
| `template_allow_user_cancel_workspace_jobs` | boolean | false | | |
| `template_display_name` | string | false | | |
| `template_icon` | string | false | | |
| `template_id` | string | false | | |
| `template_name` | string | false | | |
| `ttl_ms` | integer | false | | |
| `updated_at` | string | false | | |
## codersdk.WorkspaceAgent
@ -540,28 +660,28 @@
| Name | Type | Required | Restrictions | Description |
| ---------------------------- | ------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------- |
| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | none | none |
| `architecture` | string | false | none | none |
| `connection_timeout_seconds` | integer | false | none | none |
| `created_at` | string | false | none | none |
| `directory` | string | false | none | none |
| `disconnected_at` | string | false | none | none |
| `environment_variables` | object | false | none | none |
| » `[any property]` | string | false | none | none |
| `first_connected_at` | string | false | none | none |
| `id` | string | false | none | none |
| `instance_id` | string | false | none | none |
| `last_connected_at` | string | false | none | none |
| `latency` | object | false | none | Latency is mapped by region name (e.g. "New York City", "Seattle"). |
| » `[any property]` | [codersdk.DERPRegion](#codersdkderpregion) | false | none | none |
| `name` | string | false | none | none |
| `operating_system` | string | false | none | none |
| `resource_id` | string | false | none | none |
| `startup_script` | string | false | none | none |
| `status` | string | false | none | none |
| `troubleshooting_url` | string | false | none | none |
| `updated_at` | string | false | none | none |
| `version` | string | false | none | none |
| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | | |
| `architecture` | string | false | | |
| `connection_timeout_seconds` | integer | false | | |
| `created_at` | string | false | | |
| `directory` | string | false | | |
| `disconnected_at` | string | false | | |
| `environment_variables` | object | false | | |
| » `[any property]` | string | false | | |
| `first_connected_at` | string | false | | |
| `id` | string | false | | |
| `instance_id` | string | false | | |
| `last_connected_at` | string | false | | |
| `latency` | object | false | | Latency is mapped by region name (e.g. "New York City", "Seattle"). |
| » `[any property]` | [codersdk.DERPRegion](#codersdkderpregion) | false | | |
| `name` | string | false | | |
| `operating_system` | string | false | | |
| `resource_id` | string | false | | |
| `startup_script` | string | false | | |
| `status` | string | false | | |
| `troubleshooting_url` | string | false | | |
| `updated_at` | string | false | | |
| `version` | string | false | | |
## codersdk.WorkspaceApp
@ -587,19 +707,19 @@
### Properties
| Name | Type | Required | Restrictions | Description |
| --------------- | -------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command` | string | false | none | none |
| `display_name` | string | false | none | Display name is a friendly name for the app. |
| `external` | boolean | false | none | External specifies whether the URL should be opened externally on<br>the client or not. |
| `health` | string | false | none | none |
| `healthcheck` | [codersdk.Healthcheck](#codersdkhealthcheck) | false | none | none |
| `icon` | string | false | none | Icon is a relative path or external URL that specifies<br>an icon to be displayed in the dashboard. |
| `id` | string | false | none | none |
| `sharing_level` | string | false | none | none |
| `slug` | string | false | none | Slug is a unique identifier within the agent. |
| `subdomain` | boolean | false | none | Subdomain denotes whether the app should be accessed via a path on the<br>`coder server` or via a hostname-based dev URL. If this is set to true<br>and there is no app wildcard configured on the server, the app will not<br>be accessible in the UI. |
| `url` | string | false | none | Url is the address being proxied to inside the workspace.<br>If external is specified, this will be opened on the client. |
| Name | Type | Required | Restrictions | Description |
| --------------- | -------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` | string | false | | |
| `healthcheck` | [codersdk.Healthcheck](#codersdkhealthcheck) | false | | |
| `icon` | string | false | | Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard. |
| `id` | string | false | | |
| `sharing_level` | string | 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. |
## codersdk.WorkspaceBuild
@ -721,25 +841,25 @@
| Name | Type | Required | Restrictions | Description |
| ----------------------- | ----------------------------------------------------------------- | -------- | ------------ | ----------- |
| `build_number` | integer | false | none | none |
| `created_at` | string | false | none | none |
| `daily_cost` | integer | false | none | none |
| `deadline` | string(time) or `null` | false | none | none |
| `id` | string | false | none | none |
| `initiator_id` | string | false | none | none |
| `initiator_name` | string | false | none | none |
| `job` | [codersdk.ProvisionerJob](#codersdkprovisionerjob) | false | none | none |
| `reason` | string | false | none | none |
| `resources` | array of [codersdk.WorkspaceResource](#codersdkworkspaceresource) | false | none | none |
| `status` | string | false | none | none |
| `template_version_id` | string | false | none | none |
| `template_version_name` | string | false | none | none |
| `transition` | string | false | none | none |
| `updated_at` | string | false | none | none |
| `workspace_id` | string | false | none | none |
| `workspace_name` | string | false | none | none |
| `workspace_owner_id` | string | false | none | none |
| `workspace_owner_name` | string | false | none | none |
| `build_number` | integer | false | | |
| `created_at` | string | false | | |
| `daily_cost` | integer | false | | |
| `deadline` | string(time) or `null` | false | | |
| `id` | string | false | | |
| `initiator_id` | string | false | | |
| `initiator_name` | string | false | | |
| `job` | [codersdk.ProvisionerJob](#codersdkprovisionerjob) | false | | |
| `reason` | string | false | | |
| `resources` | array of [codersdk.WorkspaceResource](#codersdkworkspaceresource) | false | | |
| `status` | string | false | | |
| `template_version_id` | string | false | | |
| `template_version_name` | string | false | | |
| `transition` | string | false | | |
| `updated_at` | string | false | | |
| `workspace_id` | string | false | | |
| `workspace_name` | string | false | | |
| `workspace_owner_id` | string | false | | |
| `workspace_owner_name` | string | false | | |
#### Enumerated Values
@ -840,17 +960,17 @@
| Name | Type | Required | Restrictions | Description |
| ---------------------- | --------------------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `agents` | array of [codersdk.WorkspaceAgent](#codersdkworkspaceagent) | false | none | none |
| `created_at` | string | false | none | none |
| `daily_cost` | integer | false | none | none |
| `hide` | boolean | false | none | none |
| `icon` | string | false | none | none |
| `id` | string | false | none | none |
| `job_id` | string | false | none | none |
| `metadata` | array of [codersdk.WorkspaceResourceMetadata](#codersdkworkspaceresourcemetadata) | false | none | none |
| `name` | string | false | none | none |
| `type` | string | false | none | none |
| `workspace_transition` | string | false | none | none |
| `agents` | array of [codersdk.WorkspaceAgent](#codersdkworkspaceagent) | false | | |
| `created_at` | string | false | | |
| `daily_cost` | integer | false | | |
| `hide` | boolean | false | | |
| `icon` | string | false | | |
| `id` | string | false | | |
| `job_id` | string | false | | |
| `metadata` | array of [codersdk.WorkspaceResourceMetadata](#codersdkworkspaceresourcemetadata) | false | | |
| `name` | string | false | | |
| `type` | string | false | | |
| `workspace_transition` | string | false | | |
#### Enumerated Values
@ -874,9 +994,9 @@
| Name | Type | Required | Restrictions | Description |
| ----------- | ------- | -------- | ------------ | ----------- |
| `key` | string | false | none | none |
| `sensitive` | boolean | false | none | none |
| `value` | string | false | none | none |
| `key` | string | false | | |
| `sensitive` | boolean | false | | |
| `value` | string | false | | |
## codersdk.WorkspacesResponse
@ -1016,5 +1136,5 @@
| Name | Type | Required | Restrictions | Description |
| ------------ | ------------------------------------------------- | -------- | ------------ | ----------- |
| `count` | integer | false | none | none |
| `workspaces` | array of [codersdk.Workspace](#codersdkworkspace) | false | none | none |
| `count` | integer | false | | |
| `workspaces` | array of [codersdk.Workspace](#codersdkworkspace) | false | | |

47
docs/api/templates.md
View File

@ -12,7 +12,6 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization-id}/tem
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /organizations/{organization-id}/templates/`
@ -99,7 +98,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /organizations/{organization}/templates`
@ -159,27 +157,27 @@ Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ---------------------------------- | --------------------------------- | -------- | ------------ | ------------------------------------------ |
| _anonymous_ | array | false | none | none |
| » active_user_count | integer | false | none | ActiveUserCount is set to -1 when loading. |
| » active_version_id | string | false | none | none |
| » allow_user_cancel_workspace_jobs | boolean | false | none | none |
| » build_time_stats | `codersdk.TemplateBuildTimeStats` | false | none | none |
| »» **additionalProperties** | `codersdk.TransitionStats` | false | none | none |
| »»» p50 | integer | false | none | none |
| »»» p95 | integer | false | none | none |
| » created_at | string | false | none | none |
| » created_by_id | string | false | none | none |
| » created_by_name | string | false | none | none |
| » default_ttl_ms | integer | false | none | none |
| » description | string | false | none | none |
| » display_name | string | false | none | none |
| » icon | string | false | none | none |
| » id | string | false | none | none |
| » name | string | false | none | none |
| » organization_id | string | false | none | none |
| » provisioner | string | false | none | none |
| » updated_at | string | false | none | none |
| » workspace_owner_count | integer | false | none | none |
| _anonymous_ | array | false | | |
| » active_user_count | integer | false | | ActiveUserCount is set to -1 when loading. |
| » active_version_id | string | false | | |
| » allow_user_cancel_workspace_jobs | boolean | false | | |
| » build_time_stats | `codersdk.TemplateBuildTimeStats` | false | | |
| »» **additionalProperties** | `codersdk.TransitionStats` | false | | |
| »»» p50 | integer | false | | |
| »»» p95 | integer | false | | |
| » created_at | string | false | | |
| » created_by_id | string | false | | |
| » created_by_name | string | false | | |
| » default_ttl_ms | integer | false | | |
| » description | string | false | | |
| » display_name | string | false | | |
| » icon | string | false | | |
| » id | string | false | | |
| » name | string | false | | |
| » organization_id | string | false | | |
| » provisioner | string | false | | |
| » updated_at | string | false | | |
| » workspace_owner_count | integer | false | | |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
@ -192,7 +190,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templates/{template-name} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /organizations/{organization}/templates/{template-name}`
@ -256,7 +253,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/templates/{id} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /templates/{id}`
@ -319,7 +315,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X DELETE http://coder-server:8080/api/v2/templates/{id} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`DELETE /templates/{id}`

27
docs/api/workspaces.md
View File

@ -11,7 +11,6 @@
curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/members/{user}/workspaces \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /organizations/{organization}/members/{user}/workspaces`
@ -175,7 +174,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacename} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /users/{user}/workspace/{workspacename}`
@ -340,7 +338,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/workspaces \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /workspaces`
@ -526,7 +523,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/workspaces/{id} \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /workspaces/{id}`
@ -690,7 +686,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X PATCH http://coder-server:8080/api/v2/workspaces/{workspace} \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PATCH /workspaces/{workspace}`
@ -712,9 +707,9 @@ curl -X PATCH http://coder-server:8080/api/v2/workspaces/{workspace} \
### Responses
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | --------- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | no schema |
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
@ -727,7 +722,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/autostart \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /workspaces/{workspace}/autostart`
@ -749,9 +743,9 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/autostart \
### Responses
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | --------- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | no schema |
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
@ -765,7 +759,6 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/extend \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /workspaces/{workspace}/extend`
@ -819,7 +812,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/ttl \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /workspaces/{workspace}/ttl`
@ -841,9 +833,9 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/ttl \
### Responses
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | --------- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | no schema |
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.
@ -856,7 +848,6 @@ To perform this operation, you must be authenticated by means of one of the foll
curl -X GET http://coder-server:8080/api/v2/workspaces/{workspace}/watch \
-H 'Accept: text/event-stream' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /workspaces/{workspace}/watch`

8
docs/manifest.json
View File

@ -329,6 +329,14 @@
"title": "Authentication",
"path": "./api/authentication.md"
},
{
"title": "Applications",
"path": "./api/applications.md"
},
{
"title": "Authorization",
"path": "./api/authorization.md"
},
{
"title": "Templates",
"path": "./api/templates.md"

4
scripts/apidocgen/markdown-template/code_shell.dot
View File

@ -1,4 +1,4 @@
# Example request using curl
curl -X {{=data.methodUpper}} http://coder-server:8080{{=data.url}}{{=data.requiredQueryString}}{{?data.allHeaders.length}} \{{?}}
{{~data.allHeaders :p:index}} -H '{{=p.name}}: {{=p.exampleValues.object}}'{{?index < data.allHeaders.length-1}} \{{?}}
{{~}}
{{~data.allHeaders :p:index}} -H '{{=p.name}}: {{=p.exampleValues.object}}'{{?index < data.allHeaders.length-1}} \
{{?}}{{~}}

20
scripts/apidocgen/markdown-template/main.dot
View File

@ -30,26 +30,22 @@
function renderDescription(p) {
if (!p.description) {
return "none";
return "";
}
const toSnakeCase = str =>
str
.match(/[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g)
.map(x => x.toLowerCase())
.join('_');
const words = p.description.split(' ');
const description = p.description.replaceAll("<br><br>", "\n").replaceAll("<br>", " ");
const words = description.split(' ');
if (words.length == 0) {
return "none";
return "";
}
const countUppercase = words[0].length - words[0].replace(/[A-Z]/g, '').length;
if (countUppercase > 1) {
const displayName = p.displayName.charAt(0).toUpperCase() + p.displayName.replaceAll("_", " ").toLowerCase().slice(1);
let displayName = p.displayName.replaceAll("» **additionalProperties**", "It");
displayName = displayName.charAt(0).toUpperCase() + displayName.replaceAll("_", " ").toLowerCase().slice(1);
return displayName + " " + words.slice(1).join(' ');
}
return p.description;
return description;
}
}}
@ -130,7 +126,7 @@
{{? block.rows.length}}|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|{{?}}
{{~ block.rows :p}}|{{= renderDisplayName(p)}}|{{= renderPropertyType(p)}}|{{=p.required}}|{{=p.restrictions||'none'}}|{{= renderDescription(p)}}|
{{~ block.rows :p}}|{{= renderDisplayName(p)}}|{{= renderPropertyType(p)}}|{{=p.required}}|{{=p.restrictions||''}}|{{= renderDescription(p)}}|
{{~}}
{{~}}
{{? (blocks[0].rows.length === 0) && (blocks.length === 1) }}

8
scripts/apidocgen/markdown-template/operation.dot
View File

@ -1,3 +1,9 @@
{{
function renderCodeSample(data) {
const originalCodeSample = data.utils.getCodeSamples(data);
return originalCodeSample.replace("\n```\n", "```\n")
}
}}
{{= data.tags.section }}
## {{= data.operationUniqueName}}
@ -14,7 +20,7 @@
{{? data.options.codeSamples || data.operation["x-code-samples"] }}
### Code samples
{{= data.utils.getCodeSamples(data)}}
{{=renderCodeSample(data)}}
{{?}}
`{{= data.methodUpper}} {{=data.method.path}}`

2
scripts/apidocgen/markdown-template/parameters.def
View File

@ -13,7 +13,7 @@
|Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{= renderParameterType(p)}}|{{=p.required}}|{{=p.shortDesc || 'none'}}|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{= renderParameterType(p)}}|{{=p.required}}|{{=p.shortDesc||''}}|
{{~}}
{{? data.longDescs }}

8
scripts/apidocgen/markdown-template/responses.def
View File

@ -6,7 +6,7 @@
break;
}
if (!content) {
return "no schema";
return "";
}
var ref = content.schema["x-widdershins-oldRef"];
@ -42,7 +42,7 @@
|Status|Meaning|Description|Schema|
|---|---|---|---|
{{~ data.responses :r}}|{{=r.status}}|{{=r.meaning}}|{{=r.description || 'none'}}|{{= renderResponseType(r)}}|
{{~ data.responses :r}}|{{=r.status}}|{{=r.meaning}}|{{=r.description||''}}|{{= renderResponseType(r)}}|
{{~}}
{{ data.responseSchemas = false; }}
@ -77,7 +77,7 @@ Status Code **{{=response.status}}**
{{?}}
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
{{~block.rows :p}}|{{=p.displayName}}|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||'none'}}|{{=p.description||'none'}}|
{{~block.rows :p}}|{{=p.displayName}}|{{? p.$ref}}`{{=p.$ref}}`{{?}}{{? !p.$ref}}{{=p.type}}{{?}}|{{=p.required}}|{{=p.restrictions||''}}|{{=p.description||''}}|
{{~}}
{{~}}
{{?}}
@ -106,7 +106,7 @@ Status Code **{{=response.status}}**
|Status|Header|Type|Format|Description|
|---|---|---|---|---|
{{~ data.responseHeaders :h}}|{{=h.status}}|{{=h.header}}|{{=h.type}}|{{=h.format||''}}|{{=h.description||'none'}}|
{{~ data.responseHeaders :h}}|{{=h.status}}|{{=h.header}}|{{=h.type}}|{{=h.format||''}}|{{=h.description||''}}|
{{~}}
{{?}}