docs: custom API use cases

coder · bpmct · Jul 13, 2023 · Jul 11, 2023 · Jul 11, 2023 · Jul 11, 2023
commit 5e1a1ce51189141c5a135eb2d70b772c29798b8c
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/workspaceagents.go b/coderd/workspaceagents.go
@@ -242,7 +242,6 @@ func (api *API) postWorkspaceAgentStartup(rw http.ResponseWriter, r *http.Reques
 // @Param request body agentsdk.PatchStartupLogs true "Startup logs"
 // @Success 200 {object} codersdk.Response
 // @Router /workspaceagents/me/startup-logs [patch]
-// @x-apidocgen {"skip": true}
 func (api *API) patchWorkspaceAgentStartupLogs(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceAgent := httpmw.WorkspaceAgent(r)
@@ -1292,7 +1291,6 @@ func convertWorkspaceAgent(derpMap *tailcfg.DERPMap, coordinator tailnet.Coordin
 // @Param request body agentsdk.Stats true "Stats request"
 // @Success 200 {object} agentsdk.StatsResponse
 // @Router /workspaceagents/me/report-stats [post]
-// @x-apidocgen {"skip": true}
 func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

diff --git a/docs/admin/automation.md b/docs/admin/automation.md
@@ -1,32 +1,86 @@
 # Automation
 
-We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md).
+All actions possible through the Coder dashboard can also be automated as it utilizes the same public REST API. There are several ways to extend/automate Coder:
 
-## Authentication
+- [CLI](../cli.md)
+- [REST API](../api/)
+- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/codersdk)
 
-Coder uses authentication tokens to grant machine users access to the REST API. Follow the [Authentication](../api/authentication.md) page to learn how to generate long-lived tokens.
+## Quickstart
 
-## CLI
+Generate a token on your Coder deployment by visiting:
 
-You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN`
-environment variable.
-
-```console
-export CODER_URL=https://coder.example.com
-export CODER_SESSION_TOKEN=*****
-coder workspaces ls
+```sh
+https://coder.example.com/settings/tokens
 ```
 
-## REST API
+List your workspaces
 
-You can review the [API reference](../api/index.md) to find the necessary routes and payload. Alternatively, you can enable the [Swagger](https://swagger.io/) endpoint to read the documentation and do requests against the API:
+```sh
+# CLI
+coder ls \
+  --url https://coder.example.com \
+  --token <your-token> \
+  --output json
 
-```console
-coder server --swagger-enable
+# REST API (with curl)
+curl https://coder.example.com/api/v2/workspaces?q=owner:me \
+  -H "Coder-Session-Token: <your-token>"
 ```
 
-By default, the local Swagger endpoint is http://localhost:3000/swagger.
+## Documentation
+
+We publish an [API reference](../api/index.md) in our documentation. You can also enable a [Swagger endpoint](../cli/server#--swagger-enable) on your Coder deployment.
+
+## Use cases
+
+We strive to keep the following use cases up to date, but please note that changes to API queries and routes can occur. For the most recent queries and payloads, we recommend checking the CLI and API documentation.
+
+### Templates
+
+- [Update templates in CI](../templates/change-management.md): Store all templates and git and update templates in CI/CD pipelines.
+
+### Workspace agents
+
+Workspace agents have a special token that can send logs, metrics, and workspace activity.
+
+- [Custom workspace logs](../api/agents.md#patch-workspace-agent-startup-logs): Expose messages prior to the Coder init script running (e.g. pulling image, VM starting, restoring snapshot). [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses this to show Kubernetes events, such as image pulls or ResourceQuota restrictions.
+
+  ```sh
+  curl -X PATCH https://dev.coder.com/api/v2/workspaceagents/me/startup-logs \
+  -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
+  -d "{
+    \"logs\": [
+      {
+        \"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
+        \"level\": \"info\",
+        \"output\": \"Restoring workspace from snapshot: 05%...\"
+      }
+    ]
+  }"
+  ```
+
+- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats): Keep a workspace "active," even if there is not an open connection (e.g. for a long-running machine learning job).
+
+  ```sh
+  #!/bin/bash
+  # Send workspace activity as long as the job is still running
 
-## Golang SDK
+  while true
+  do
+    if pgrep -f "my_training_script.py" > /dev/null
+    then
+      curl -X POST "https://coder.example.com/api/v2/workspaceagents/me/report-stats" \
+      -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
+      -d '{
+        "connection_count": 1
+      }'
 
-Coder publishes a public [Golang SDK](https://pkg.go.dev/github.com/coder/coder/codersdk) for Coder. This is consumed by the [CLI package](https://github.com/coder/coder/tree/main/cli).
+      # Sleep for 30 minutes (1800 seconds) if the job is running
+      sleep 1800
+    else
+      # Sleep for 1 minute (60 seconds) if the job is not running
+      sleep 60
+    fi
+  done
+  ```
diff --git a/docs/api/agents.md b/docs/api/agents.md
@@ -395,6 +395,137 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/manifest \
 
 To perform this operation, you must be authenticated. [Learn more](authentication.md).
 
+## Submit workspace agent stats
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/report-stats \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`POST /workspaceagents/me/report-stats`
+
+> Body parameter
+
+```json
+{
+  "connection_count": 0,
+  "connection_median_latency_ms": 0,
+  "connections_by_proto": {
+    "property1": 0,
+    "property2": 0
+  },
+  "metrics": [
+    {
+      "labels": [
+        {
+          "name": "string",
+          "value": "string"
+        }
+      ],
+      "name": "string",
+      "type": "counter",
+      "value": 0
+    }
+  ],
+  "rx_bytes": 0,
+  "rx_packets": 0,
+  "session_count_jetbrains": 0,
+  "session_count_reconnecting_pty": 0,
+  "session_count_ssh": 0,
+  "session_count_vscode": 0,
+  "tx_bytes": 0,
+  "tx_packets": 0
+}
+```
+
+### Parameters
+
+| Name   | In   | Type                                       | Required | Description   |
+| ------ | ---- | ------------------------------------------ | -------- | ------------- |
+| `body` | body | [agentsdk.Stats](schemas.md#agentsdkstats) | true     | Stats request |
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "report_interval": 0
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                     |
+| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [agentsdk.StatsResponse](schemas.md#agentsdkstatsresponse) |
+
+To perform this operation, you must be authenticated. [Learn more](authentication.md).
+
+## Patch workspace agent startup logs
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/startup-logs \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`PATCH /workspaceagents/me/startup-logs`
+
+> Body parameter
+
+```json
+{
+  "logs": [
+    {
+      "created_at": "string",
+      "level": "trace",
+      "output": "string"
+    }
+  ]
+}
+```
+
+### Parameters
+
+| Name   | In   | Type                                                             | Required | Description  |
+| ------ | ---- | ---------------------------------------------------------------- | -------- | ------------ |
+| `body` | body | [agentsdk.PatchStartupLogs](schemas.md#agentsdkpatchstartuplogs) | true     | Startup logs |
+
+### 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 agent by ID
 
 ### Code samples

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -1,4 +1,22 @@
-Get started with Coder API:
+Get started with the Coder API:
+
+## Quickstart
+
+Generate a token on your Coder deployment by visiting:
+
+```sh
+https://coder.example.com/settings/tokens
+```
+
+List your workspaces
+
+```sh
+# CLI
+curl https://coder.example.com/api/v2/workspaces?q=owner:me \
+-H "Coder-Session-Token: <your-token>"
+```
+
+## Sections
 
 <children>
   This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the `api/` directory.

diff --git a/scripts/apidocgen/postprocess/main.go b/scripts/apidocgen/postprocess/main.go
@@ -18,10 +18,28 @@ import (
 const (
 	apiSubdir       = "api"
 	apiIndexFile    = "index.md"
-	apiIndexContent = `Get started with Coder API:
+	apiIndexContent = `Get started with the Coder API:
+
+## Quickstart
+
+Generate a token on your Coder deployment by visiting:
+
+` + "````sh" + `
+https://coder.example.com/settings/tokens
+` + "````" + `
+
+List your workspaces
+
+` + "````sh" + `
+# CLI
+curl https://coder.example.com/api/v2/workspaces?q=owner:me \
+-H "Coder-Session-Token: <your-token>"
+` + "````" + `
+
+## Sections
 
 <children>
-  This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`" + `api/` + "`" + ` directory.
+  This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`api/`" + ` directory.
 </children>
 `
 )