From b7cb7f60bb5c2c366a1b8b7c608a46813b0f2b0f Mon Sep 17 00:00:00 2001 From: Mark Milligan Date: Mon, 28 Mar 2022 09:35:39 -0500 Subject: [PATCH 1/3] chore: added examples --- guides/api.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) diff --git a/guides/api.md b/guides/api.md index 7a737eba3..d52c8840f 100644 --- a/guides/api.md +++ b/guides/api.md @@ -32,3 +32,223 @@ we finalize the endpoints. + +## Examples + +These are example Coder API calls for common tasks. Note that the site-manager +role is required to be perform specific actions and without it, API results will +be limited to a user's member role. + +> Assign your Access Url, Session-Token and other resources like images and +> workspaces to variables for easier substitution in the curl commands. +> +> For example: +```sh +export ACCESS_URL "https://coder.acme.com" +export API_KEY="MUdzI3UMvF-Qlwovt-----0CL0kTbADQl" +export API_ROUTE="api/v0" +export IMAGE_ID="622b3f6e-dd6fd08-----ba38c73c9639" +``` + +### Example: get active users in 1 month increments from Jan to March 2022 +> other intervals include 1 week, 1 year, 90 day +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/metrics/usage/active-users?\ +start=2022-01-01T00:00:00.000000Z&end=2022-03-31T00:00:00.000000Z\ +&interval=1 month" \ +--header "Session-Token: $API_KEY" +``` + +### Example: get audit logs for a workspace and resource type +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/audit?\ +limit=10\ +&resource_id=$WS_ID_PHP\ +&resource_type=environment" \ + --header "Session-Token: $API_KEY" +``` + +### Example: get audit logs for workspace created in a Unix seconds period +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/audit?\ +range_start=1646092800\ +&range_end=1646697600\ +&resource_type=environment\ +&action=create" \ +--header "Session-Token: $API_KEY" +``` + +### Example: generate a session token for a user +```sh +curl --request POST \ + --url $ACCESS_URL/$API_ROUTE/api-keys/613e75c4-faef2f87-----376e1f229b6 \ + --header "Content-Type: application/json" \ + --header "Session-Token: $API_KEY" \ + --data '{ + "name": "my-session-token" + }' +``` + +### Example: get the workspaces created by a user +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/workspaces?users=$USER_ID" \ + --header "Session-Token: $API_KEY" +``` + +### Example: get the workspaces built with a specific image +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ + --header "Session-Token: $API_KEY" +``` + +### Example: get info about an image tag and workspaces built with it +> Change ```latest``` to your tag name +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID/tags/latest" \ + --header "Session-Token: $API_KEY" +``` + +### Example: get the workspaces in a specific organization +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/workspaces?orgs=$ORG_ID" \ + --header "Session-Token: $API_KEY" +``` + +### Example: get the images authorized in a specific organization +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/images/?org=$ORG_ID&workspaces=false" \ + --header "Session-Token: $API_KEY" +``` + +### Example: update image tags from a registry +```sh +curl --request POST \ + --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ + --header "Session-Token: $API_KEY" \ + --data "{}" +``` + +### Example: update the compute resources baseline for an image +```sh +curl --request PATCH \ + --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ + --header "Session-Token: $API_KEY" \ + --data "{ + \"default_memory_gb\": 8, + \"description\": \"3/26/22 increased RAM from 4 to 8 GB\" + }" +``` + +### Example: import a container image +```sh +curl --request POST \ + --url "$ACCESS_URL/$API_ROUTE/images" \ + --header "Session-Token: $API_KEY" \ + --header "Content-Type: application/json" \ + --data "{ + \"default_cpu_cores\": 4, + \"default_disk_gb\": 4, + \"default_memory_gb\": 10, + \"description\": \"IntelliJ 2020.3.4\", + \"org_id\": \"$ORG_ID\", + \"registry_id\": \"$REG_ID\", + \"repository\": \"marktmilligan/intellij-ultimate\", + \"tag\": \"2020.3.4\" +}" +``` + +### Example: deprecate an image (and its tags) +```sh +curl --request PATCH \ + --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ + --header "Session-Token: $API_KEY" \ + --data "{ + \"deprecated\": true + }" +``` + +### Example: Restart/rebuild a workspace +```sh +curl --request PATCH \ + --url $ACCESS_URL/$API_ROUTE/workspaces/$WS_ID \ + --header "Content-Type: application/json" \ + --header "Session-Token: $API_KEY" \ + --data "{}" +``` + +### Example: How to create a user +```sh +curl --request POST \ + --url "$ACCESS_URL/$API_ROUTE/users" \ + --header "Session-Token: $API_KEY" \ + --header "Content-Type: application/json" \ + --data "{ + \"email\": \"bob@acme.com\", + \"login_type\": \"built-in\", + \"name\": \"Bob Barker\", + \"password\": \"password\", + \"temporary_password\": true, + \"username\": \"bbarker\", + \"organizations\": [\"default\",\"$ORG_ID\"] +}" +``` + +### Example: Get a user's public SSH key +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/users/$USER_ID/sshkey" \ + --header "Session-Token: $API_KEY" +``` + +### Example: Create a dev URL +```sh +curl --request POST \ + --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \ + --header "Session-Token: $API_KEY" \ + --header "Content-Type: application/json" \ + --data "{ + \"access\": \"PRIVATE\", + \"name\": \"phpapp4\", + \"port\": 1029, + \"scheme\": \"http\" +}" +``` + +### Example: Update a dev URL including access control level +```sh +curl --request PUT \ + --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP" \ + --header "Session-Token: $API_KEY" \ + --header "Content-Type: application/json" \ + --data "{ + \"access\": \"AUTHED\", + \"name\": \"phpapp4\", + \"port\": 1029, + \"scheme\": \"http\" +}" +``` + +### Example: List dev URLs +```sh +curl --request GET \ + --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \ + --header "Session-Token: $API_KEY" +``` + +### Example: Delete a dev URL +```sh +curl --request DELETE \ + --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP \ + --header "Session-Token: $API_KEY" \ + --header "Content-Type: application/json" \ + --data "{ +}" +``` \ No newline at end of file From 19b5cfac96296bf44534027459262479214bd828 Mon Sep 17 00:00:00 2001 From: Mark Milligan Date: Mon, 28 Mar 2022 09:45:31 -0500 Subject: [PATCH 2/3] chore: linting repairs to API examples --- guides/api.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/guides/api.md b/guides/api.md index d52c8840f..c3b5623d9 100644 --- a/guides/api.md +++ b/guides/api.md @@ -39,10 +39,11 @@ These are example Coder API calls for common tasks. Note that the site-manager role is required to be perform specific actions and without it, API results will be limited to a user's member role. -> Assign your Access Url, Session-Token and other resources like images and +> Assign your Access URL, Session-Token and other resources like images and > workspaces to variables for easier substitution in the curl commands. > > For example: + ```sh export ACCESS_URL "https://coder.acme.com" export API_KEY="MUdzI3UMvF-Qlwovt-----0CL0kTbADQl" @@ -51,7 +52,9 @@ export IMAGE_ID="622b3f6e-dd6fd08-----ba38c73c9639" ``` ### Example: get active users in 1 month increments from Jan to March 2022 + > other intervals include 1 week, 1 year, 90 day + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/metrics/usage/active-users?\ @@ -61,6 +64,7 @@ start=2022-01-01T00:00:00.000000Z&end=2022-03-31T00:00:00.000000Z\ ``` ### Example: get audit logs for a workspace and resource type + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/audit?\ @@ -71,6 +75,7 @@ limit=10\ ``` ### Example: get audit logs for workspace created in a Unix seconds period + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/audit?\ @@ -82,6 +87,7 @@ range_start=1646092800\ ``` ### Example: generate a session token for a user + ```sh curl --request POST \ --url $ACCESS_URL/$API_ROUTE/api-keys/613e75c4-faef2f87-----376e1f229b6 \ @@ -93,6 +99,7 @@ curl --request POST \ ``` ### Example: get the workspaces created by a user + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/workspaces?users=$USER_ID" \ @@ -100,6 +107,7 @@ curl --request GET \ ``` ### Example: get the workspaces built with a specific image + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ @@ -107,7 +115,9 @@ curl --request GET \ ``` ### Example: get info about an image tag and workspaces built with it + > Change ```latest``` to your tag name + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID/tags/latest" \ @@ -115,6 +125,7 @@ curl --request GET \ ``` ### Example: get the workspaces in a specific organization + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/workspaces?orgs=$ORG_ID" \ @@ -122,6 +133,7 @@ curl --request GET \ ``` ### Example: get the images authorized in a specific organization + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/images/?org=$ORG_ID&workspaces=false" \ @@ -129,6 +141,7 @@ curl --request GET \ ``` ### Example: update image tags from a registry + ```sh curl --request POST \ --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ @@ -137,6 +150,7 @@ curl --request POST \ ``` ### Example: update the compute resources baseline for an image + ```sh curl --request PATCH \ --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ @@ -148,6 +162,7 @@ curl --request PATCH \ ``` ### Example: import a container image + ```sh curl --request POST \ --url "$ACCESS_URL/$API_ROUTE/images" \ @@ -166,6 +181,7 @@ curl --request POST \ ``` ### Example: deprecate an image (and its tags) + ```sh curl --request PATCH \ --url "$ACCESS_URL/$API_ROUTE/images/$IMAGE_ID" \ @@ -176,6 +192,7 @@ curl --request PATCH \ ``` ### Example: Restart/rebuild a workspace + ```sh curl --request PATCH \ --url $ACCESS_URL/$API_ROUTE/workspaces/$WS_ID \ @@ -185,6 +202,7 @@ curl --request PATCH \ ``` ### Example: How to create a user + ```sh curl --request POST \ --url "$ACCESS_URL/$API_ROUTE/users" \ @@ -202,6 +220,7 @@ curl --request POST \ ``` ### Example: Get a user's public SSH key + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/users/$USER_ID/sshkey" \ @@ -209,6 +228,7 @@ curl --request GET \ ``` ### Example: Create a dev URL + ```sh curl --request POST \ --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \ @@ -223,6 +243,7 @@ curl --request POST \ ``` ### Example: Update a dev URL including access control level + ```sh curl --request PUT \ --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP" \ @@ -237,6 +258,7 @@ curl --request PUT \ ``` ### Example: List dev URLs + ```sh curl --request GET \ --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls" \ @@ -244,6 +266,7 @@ curl --request GET \ ``` ### Example: Delete a dev URL + ```sh curl --request DELETE \ --url "$ACCESS_URL/$API_ROUTE/workspaces/$WS_ID_PHP/devurls/$DU_ID_PHP \ @@ -251,4 +274,4 @@ curl --request DELETE \ --header "Content-Type: application/json" \ --data "{ }" -``` \ No newline at end of file +``` From 1661cabb825ef8feff17f2a812934576e8384b7d Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Mon, 28 Mar 2022 10:00:30 -0500 Subject: [PATCH 3/3] minor edits --- guides/api.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/guides/api.md b/guides/api.md index c3b5623d9..d06571f9e 100644 --- a/guides/api.md +++ b/guides/api.md @@ -7,6 +7,15 @@ state: alpha To help you integrate Coder into your automated workflows, we've documented our API. +## Documentation + +Please note that the API is under active development; expect breaking changes as +we finalize the endpoints. + + + + + ## Authentication Use of the API requires authentication with a session token. You can generate @@ -24,15 +33,6 @@ one using the [Coder CLI](../cli/index.md): -H "Session-Token: Bk...nt" ``` -## Documentation - -Please note that the API is under active development; expect breaking changes as -we finalize the endpoints. - - - - - ## Examples These are example Coder API calls for common tasks. Note that the site-manager @@ -41,8 +41,6 @@ be limited to a user's member role. > Assign your Access URL, Session-Token and other resources like images and > workspaces to variables for easier substitution in the curl commands. -> -> For example: ```sh export ACCESS_URL "https://coder.acme.com" @@ -53,7 +51,7 @@ export IMAGE_ID="622b3f6e-dd6fd08-----ba38c73c9639" ### Example: get active users in 1 month increments from Jan to March 2022 -> other intervals include 1 week, 1 year, 90 day +> Other intervals include 1 week, 1 year, 90 day ```sh curl --request GET \