Skip to content

Commit fa4b267

Browse files
sharkymarkericpaulsen
sharkymark
and
ericpaulsen
authored
chore: added examples for APIs (#924)
* chore: added examples * chore: linting repairs to API examples * minor edits Co-authored-by: Eric Paulsen <ericpaulsen@coder.com>
1 parent 72b5ceb commit fa4b267

File tree

1 file changed

+247
-6
lines changed

1 file changed

+247
-6
lines changed

‎guides/api.md

Lines changed: 247 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ state: alpha
77
To help you integrate Coder into your automated workflows, we've documented our
88
API.
99

10+
## Documentation
11+
12+
Please note that the API is under active development; expect breaking changes as
13+
we finalize the endpoints.
14+
15+
<a href="https://apidocs.coder.com">
16+
<button> Swagger Docs </button>
17+
</a>
18+
1019
## Authentication
1120

1221
Use of the API requires authentication with a session token. You can generate
@@ -24,11 +33,243 @@ one using the [Coder CLI](../cli/index.md):
2433
-H "Session-Token: Bk...nt"
2534
```
2635

27-
## Documentation
36+
## Examples
2837

29-
Please note that the API is under active development; expect breaking changes as
30-
we finalize the endpoints.
38+
These are example Coder API calls for common tasks. Note that the site-manager
39+
role is required to be perform specific actions and without it, API results will
40+
be limited to a user's member role.
3141

32-
<a href="https://apidocs.coder.com">
33-
<button> Swagger Docs </button>
34-
</a>
42+
> Assign your Access URL, Session-Token and other resources like images and
43+
> workspaces to variables for easier substitution in the curl commands.
44+
45+
```sh
46+
export ACCESS_URL "https://coder.acme.com"
47+
export API_KEY="MUdzI3UMvF-Qlwovt-----0CL0kTbADQl"
48+
export API_ROUTE="api/v0"
49+
export IMAGE_ID="622b3f6e-dd6fd08-----ba38c73c9639"
50+
```
51+
52+
### Example: get active users in 1 month increments from Jan to March 2022
53+
54+
> Other intervals include 1 week, 1 year, 90 day
55+
56+
```sh
57+
curl --request GET \
58+
--url "$ACCESS_URL/$API_ROUTE/metrics/usage/active-users?\
59+
start=2022-01-01T00:00:00.000000Z&end=2022-03-31T00:00:00.000000Z\
60+
&interval=1 month" \
61+
--header "Session-Token: $API_KEY"
62+
```
63+
64+
### Example: get audit logs for a workspace and resource type
65+
66+
```sh
67+
curl --request GET \
68+
--url "$ACCESS_URL/$API_ROUTE/audit?\
69+
limit=10\
70+
&resource_id=$WS_ID_PHP\
71+
&resource_type=environment" \
72+
--header "Session-Token: $API_KEY"
73+
```
74+
75+
### Example: get audit logs for workspace created in a Unix seconds period
76+
77+
```sh
78+
curl --request GET \
79+
--url "$ACCESS_URL/$API_ROUTE/audit?\
80+
range_start=1646092800\
81+
&range_end=1646697600\
82+
&resource_type=environment\
83+
&action=create" \
84+
--header "Session-Token: $API_KEY"
85+
```
86+
87+
### Example: generate a session token for a user
88+
89+
```sh
90+
curl --request POST \
91+
--url $ACCESS_URL/$API_ROUTE/api-keys/613e75c4-faef2f87-----376e1f229b6 \
92+
--header "Content-Type: application/json" \
93+
--header "Session-Token: $API_KEY" \
94+
--data '{
95+
"name": "my-session-token"
96+
}'
97+
```
98+
99+
### Example: get the workspaces created by a user
100+
101+
```sh
102+
curl --request GET \
103+
--url "$ACCESS_URL/$API_ROUTE/workspaces?users=$USER_ID" \
104+
--header "Session-Token: $API_KEY"
105+
```
106+
107+
### Example: get the workspaces built with a specific image
108+
109+
```sh
110+
curl --request GET \
111+
--url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
112+
--header "Session-Token: $API_KEY"
113+
```
114+
115+
### Example: get info about an image tag and workspaces built with it
116+
117+
> Change ```latest``` to your tag name
118+
119+
```sh
120+
curl --request GET \
121+
--url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID/tags/latest" \
122+
--header "Session-Token: $API_KEY"
123+
```
124+
125+
### Example: get the workspaces in a specific organization
126+
127+
```sh
128+
curl --request GET \
129+
--url "$ACCESS_URL/$API_ROUTE/workspaces?orgs=$ORG_ID" \
130+
--header "Session-Token: $API_KEY"
131+
```
132+
133+
### Example: get the images authorized in a specific organization
134+
135+
```sh
136+
curl --request GET \
137+
--url "$ACCESS_URL/$API_ROUTE/images/?org=$ORG_ID&workspaces=false" \
138+
--header "Session-Token: $API_KEY"
139+
```
140+
141+
### Example: update image tags from a registry
142+
143+
```sh
144+
curl --request POST \
145+
--url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
146+
--header "Session-Token: $API_KEY" \
147+
--data "{}"
148+
```
149+
150+
### Example: update the compute resources baseline for an image
151+
152+
```sh
153+
curl --request PATCH \
154+
--url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
155+
--header "Session-Token: $API_KEY" \
156+
--data "{
157+
\"default_memory_gb\": 8,
158+
\"description\": \"3/26/22 increased RAM from 4 to 8 GB\"
159+
}"
160+
```
161+
162+
### Example: import a container image
163+
164+
```sh
165+
curl --request POST \
166+
--url "$ACCESS_URL/$API_ROUTE/images" \
167+
--header "Session-Token: $API_KEY" \
168+
--header "Content-Type: application/json" \
169+
--data "{
170+
\"default_cpu_cores\": 4,
171+
\"default_disk_gb\": 4,
172+
\"default_memory_gb\": 10,
173+
\"description\": \"IntelliJ 2020.3.4\",
174+
\"org_id\": \"$ORG_ID\",
175+
\"registry_id\": \"$REG_ID\",
176+
\"repository\": \"marktmilligan/intellij-ultimate\",
177+
\"tag\": \"2020.3.4\"
178+
}"
179+
```
180+
181+
### Example: deprecate an image (and its tags)
182+
183+
```sh
184+
curl --request PATCH \
185+
--url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \
186+
--header "Session-Token: $API_KEY" \
187+
--data "{
188+
\"deprecated\": true
189+
}"
190+
```
191+
192+
### Example: Restart/rebuild a workspace
193+
194+
```sh
195+
curl --request PATCH \
196+
--url $ACCESS_URL/$API_ROUTE/workspaces/$WS_ID \
197+
--header "Content-Type: application/json" \
198+
--header "Session-Token: $API_KEY" \
199+
--data "{}"
200+
```
201+
202+
### Example: How to create a user
203+
204+
```sh
205+
curl --request POST \
206+
--url "$ACCESS_URL/$API_ROUTE/users" \
207+
--header "Session-Token: $API_KEY" \
208+
--header "Content-Type: application/json" \
209+
--data "{
210+
\"email\": \"bob@acme.com\",
211+
\"login_type\": \"built-in\",
212+
\"name\": \"Bob Barker\",
213+
\"password\": \"password\",
214+
\"temporary_password\": true,
215+
\"username\": \"bbarker\",
216+
\"organizations\": [\"default\",\"$ORG_ID\"]
217+
}"
218+
```
219+
220+
### Example: Get a user's public SSH key
221+
222+
```sh
223+
curl --request GET \
224+
--url "$ACCESS_URL/$API_ROUTE/users/$USER_ID/sshkey" \
225+
--header "Session-Token: $API_KEY"
226+
```
227+
228+
### Example: Create a dev URL
229+
230+
```sh
231+
curl --request POST \
232+
--url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \
233+
--header "Session-Token: $API_KEY" \
234+
--header "Content-Type: application/json" \
235+
--data "{
236+
\"access\": \"PRIVATE\",
237+
\"name\": \"phpapp4\",
238+
\"port\": 1029,
239+
\"scheme\": \"http\"
240+
}"
241+
```
242+
243+
### Example: Update a dev URL including access control level
244+
245+
```sh
246+
curl --request PUT \
247+
--url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP" \
248+
--header "Session-Token: $API_KEY" \
249+
--header "Content-Type: application/json" \
250+
--data "{
251+
\"access\": \"AUTHED\",
252+
\"name\": \"phpapp4\",
253+
\"port\": 1029,
254+
\"scheme\": \"http\"
255+
}"
256+
```
257+
258+
### Example: List dev URLs
259+
260+
```sh
261+
curl --request GET \
262+
--url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \
263+
--header "Session-Token: $API_KEY"
264+
```
265+
266+
### Example: Delete a dev URL
267+
268+
```sh
269+
curl --request DELETE \
270+
--url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP \
271+
--header "Session-Token: $API_KEY" \
272+
--header "Content-Type: application/json" \
273+
--data "{
274+
}"
275+
```

0 commit comments

Comments
 (0)