Skip to content

Commit 44e2518

Browse files
bpmctbpmct
authored
docs: add custom API use cases (#8445)
1 parent ebdc510 commit 44e2518

File tree

7 files changed

+250
-35
lines changed

7 files changed

+250
-35
lines changed

‎coderd/apidoc/docs.go

-6
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎coderd/apidoc/swagger.json

-6
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎coderd/workspaceagents.go

-2
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,6 @@ func (api *API) postWorkspaceAgentStartup(rw http.ResponseWriter, r *http.Reques
243243
// @Param request body agentsdk.PatchStartupLogs true "Startup logs"
244244
// @Success 200 {object} codersdk.Response
245245
// @Router /workspaceagents/me/startup-logs [patch]
246-
// @x-apidocgen {"skip": true}
247246
func (api *API) patchWorkspaceAgentStartupLogs(rw http.ResponseWriter, r *http.Request) {
248247
ctx := r.Context()
249248
workspaceAgent := httpmw.WorkspaceAgent(r)
@@ -1297,7 +1296,6 @@ func convertWorkspaceAgent(derpMap *tailcfg.DERPMap, coordinator tailnet.Coordin
12971296
// @Param request body agentsdk.Stats true "Stats request"
12981297
// @Success 200 {object} agentsdk.StatsResponse
12991298
// @Router /workspaceagents/me/report-stats [post]
1300-
// @x-apidocgen {"skip": true}
13011299
func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Request) {
13021300
ctx := r.Context()
13031301

‎docs/admin/automation.md

+72-18
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,86 @@
11
# Automation
22

3-
We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md).
3+
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:
44

5-
## Authentication
5+
- [CLI](../cli.md)
6+
- [REST API](../api/)
7+
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/codersdk)
68

7-
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.
9+
## Quickstart
810

9-
## CLI
11+
Generate a token on your Coder deployment by visiting:
1012

11-
You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN`
12-
environment variable.
13-
14-
```console
15-
export CODER_URL=https://coder.example.com
16-
export CODER_SESSION_TOKEN=*****
17-
coder workspaces ls
13+
```sh
14+
https://coder.example.com/settings/tokens
1815
```
1916

20-
## REST API
17+
List your workspaces
2118

22-
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:
19+
```sh
20+
# CLI
21+
coder ls \
22+
--url https://coder.example.com \
23+
--token <your-token> \
24+
--output json
2325

24-
```console
25-
coder server --swagger-enable
26+
# REST API (with curl)
27+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
28+
-H "Coder-Session-Token: <your-token>"
2629
```
2730

28-
By default, the local Swagger endpoint is http://localhost:3000/swagger.
31+
## Documentation
32+
33+
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.
34+
35+
## Use cases
36+
37+
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.
38+
39+
### Templates
40+
41+
- [Update templates in CI](../templates/change-management.md): Store all templates and git and update templates in CI/CD pipelines.
42+
43+
### Workspace agents
44+
45+
Workspace agents have a special token that can send logs, metrics, and workspace activity.
46+
47+
- [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.
48+
49+
```sh
50+
curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/startup-logs \
51+
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
52+
-d "{
53+
\"logs\": [
54+
{
55+
\"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
56+
\"level\": \"info\",
57+
\"output\": \"Restoring workspace from snapshot: 05%...\"
58+
}
59+
]
60+
}"
61+
```
62+
63+
- [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).
64+
65+
```sh
66+
#!/bin/bash
67+
# Send workspace activity as long as the job is still running
2968

30-
## Golang SDK
69+
while true
70+
do
71+
if pgrep -f "my_training_script.py" > /dev/null
72+
then
73+
curl -X POST "https://coder.example.com/api/v2/workspaceagents/me/report-stats" \
74+
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
75+
-d '{
76+
"connection_count": 1
77+
}'
3178

32-
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).
79+
# Sleep for 30 minutes (1800 seconds) if the job is running
80+
sleep 1800
81+
else
82+
# Sleep for 1 minute (60 seconds) if the job is not running
83+
sleep 60
84+
fi
85+
done
86+
```

‎docs/api/agents.md

+131
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,137 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/manifest \
396396

397397
To perform this operation, you must be authenticated. [Learn more](authentication.md).
398398

399+
## Submit workspace agent stats
400+
401+
### Code samples
402+
403+
```shell
404+
# Example request using curl
405+
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/report-stats \
406+
-H 'Content-Type: application/json' \
407+
-H 'Accept: application/json' \
408+
-H 'Coder-Session-Token: API_KEY'
409+
```
410+
411+
`POST /workspaceagents/me/report-stats`
412+
413+
> Body parameter
414+
415+
```json
416+
{
417+
"connection_count": 0,
418+
"connection_median_latency_ms": 0,
419+
"connections_by_proto": {
420+
"property1": 0,
421+
"property2": 0
422+
},
423+
"metrics": [
424+
{
425+
"labels": [
426+
{
427+
"name": "string",
428+
"value": "string"
429+
}
430+
],
431+
"name": "string",
432+
"type": "counter",
433+
"value": 0
434+
}
435+
],
436+
"rx_bytes": 0,
437+
"rx_packets": 0,
438+
"session_count_jetbrains": 0,
439+
"session_count_reconnecting_pty": 0,
440+
"session_count_ssh": 0,
441+
"session_count_vscode": 0,
442+
"tx_bytes": 0,
443+
"tx_packets": 0
444+
}
445+
```
446+
447+
### Parameters
448+
449+
| Name | In | Type | Required | Description |
450+
| ------ | ---- | ------------------------------------------ | -------- | ------------- |
451+
| `body` | body | [agentsdk.Stats](schemas.md#agentsdkstats) | true | Stats request |
452+
453+
### Example responses
454+
455+
> 200 Response
456+
457+
```json
458+
{
459+
"report_interval": 0
460+
}
461+
```
462+
463+
### Responses
464+
465+
| Status | Meaning | Description | Schema |
466+
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
467+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.StatsResponse](schemas.md#agentsdkstatsresponse) |
468+
469+
To perform this operation, you must be authenticated. [Learn more](authentication.md).
470+
471+
## Patch workspace agent startup logs
472+
473+
### Code samples
474+
475+
```shell
476+
# Example request using curl
477+
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/startup-logs \
478+
-H 'Content-Type: application/json' \
479+
-H 'Accept: application/json' \
480+
-H 'Coder-Session-Token: API_KEY'
481+
```
482+
483+
`PATCH /workspaceagents/me/startup-logs`
484+
485+
> Body parameter
486+
487+
```json
488+
{
489+
"logs": [
490+
{
491+
"created_at": "string",
492+
"level": "trace",
493+
"output": "string"
494+
}
495+
]
496+
}
497+
```
498+
499+
### Parameters
500+
501+
| Name | In | Type | Required | Description |
502+
| ------ | ---- | ---------------------------------------------------------------- | -------- | ------------ |
503+
| `body` | body | [agentsdk.PatchStartupLogs](schemas.md#agentsdkpatchstartuplogs) | true | Startup logs |
504+
505+
### Example responses
506+
507+
> 200 Response
508+
509+
```json
510+
{
511+
"detail": "string",
512+
"message": "string",
513+
"validations": [
514+
{
515+
"detail": "string",
516+
"field": "string"
517+
}
518+
]
519+
}
520+
```
521+
522+
### Responses
523+
524+
| Status | Meaning | Description | Schema |
525+
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ |
526+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) |
527+
528+
To perform this operation, you must be authenticated. [Learn more](authentication.md).
529+
399530
## Get workspace agent by ID
400531

401532
### Code samples

‎docs/api/index.md

+23-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,26 @@
1-
Get started with Coder API:
1+
Get started with the Coder API:
2+
3+
## Quickstart
4+
5+
Generate a token on your Coder deployment by visiting:
6+
7+
```sh
8+
https://coder.example.com/settings/tokens
9+
```
10+
11+
List your workspaces
12+
13+
```sh
14+
# CLI
15+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
16+
-H "Coder-Session-Token: <your-token>"
17+
```
18+
19+
## Use cases
20+
21+
See some common [use cases](../admin/automation.md#use-cases) for the REST API.
22+
23+
## Sections
224

325
<children>
426
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the `api/` directory.

‎scripts/apidocgen/postprocess/main.go

+24-2
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,32 @@ import (
1818
const (
1919
apiSubdir = "api"
2020
apiIndexFile = "index.md"
21-
apiIndexContent = `Get started with Coder API:
21+
apiIndexContent = `Get started with the Coder API:
22+
23+
## Quickstart
24+
25+
Generate a token on your Coder deployment by visiting:
26+
27+
` + "````sh" + `
28+
https://coder.example.com/settings/tokens
29+
` + "````" + `
30+
31+
List your workspaces
32+
33+
` + "````sh" + `
34+
# CLI
35+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
36+
-H "Coder-Session-Token: <your-token>"
37+
` + "````" + `
38+
39+
## Use cases
40+
41+
See some common [use cases](../admin/automation.md#use-cases) for the REST API.
42+
43+
## Sections
2244
2345
<children>
24-
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`" + `api/` + "`" + ` directory.
46+
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`api/`" + ` directory.
2547
</children>
2648
`
2749
)

0 commit comments

Comments
 (0)