Skip to content

Commit 99099c4

Browse files
authored
Introduce documentation for the TypeDB Cloud API (#915)
## What is the goal of this PR? We add documentation pages for the TypeDB Cloud API, containing: - A brief description of how to setup and use the API - A more detailed list of each API endpoint ## What are the changes implemented in this PR? Add the above pages.
1 parent 2d2bb7a commit 99099c4

File tree

11 files changed

+1227
-0
lines changed

11 files changed

+1227
-0
lines changed

home/modules/ROOT/pages/quickstart.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ In 3 minutes, set up TypeDB to run your first queries.
99

1010
// video::UQbdl35ymOg[youtube,role=framed]
1111

12+
// tag::content[]
1213
[#_create_free_cluster]
1314
== Create a free cluster
1415
@@ -34,6 +35,7 @@ Once your cluster is online, the *Connect to your cluster* dialog will display t
3435
====
3536
You'll be connected as the default database user, which is created with admin privileges.
3637
====
38+
// end::content[]
3739
3840
3941
[#_next_steps]
Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
= TypeDB Cloud Administration API
2+
3+
The TypeDB Cloud administration API can be used to perform certain
4+
actions programmatically, rather than through the TypeDB Cloud website.
5+
6+
To use the API, you will need to sign up for a free TypeDB Cloud account at
7+
https://cloud.typedb.com/sign-up.
8+
9+
== Generate an API Token
10+
11+
1. Visit your https://cloud.typedb.com/?org_action=/settings[organization settings] page,
12+
scroll to the API tokens section, and click "Generate API Token".
13+
14+
2. Give your API token a descriptive name, and appropriate access to your chosen project.
15+
See the xref:{page-version}@manual::cloud/api/reference.adoc#accesslevels[API reference] for detailed access level info.
16+
17+
3. Generate your API token and copy the displayed client ID and client secret for later use when authenticating.
18+
19+
[IMPORTANT]
20+
====
21+
Make sure to save the client secret somewhere safe - you will only see it when
22+
you first generate the token, and will be unable to use the token without it.
23+
====
24+
25+
== Access the API
26+
27+
Once you have your client ID and client secret,
28+
you will need to exchange these for a short-lived access token used to query the API.
29+
30+
. Make a `POST` request to `\https://cloud.typedb.com/api/auth`,
31+
with the client ID and client secret in a Basic authorization header, separated by a `:`.
32+
+
33+
[tabs]
34+
====
35+
curl::
36+
+
37+
[source,console]
38+
----
39+
curl --request POST \
40+
--url https://cloud.typedb.com/api/auth \
41+
--header 'Authorization: Basic {CLIENT-ID}:{CLIENT-SECRET}'
42+
----
43+
44+
Python::
45+
+
46+
[source,python]
47+
----
48+
import requests
49+
50+
url = "https://cloud.typedb.com/api/auth"
51+
52+
headers = {
53+
"Authorization": "Basic {CLIENT-ID}:{CLIENT-SECRET}"
54+
}
55+
56+
response = requests.post(url, headers=headers)
57+
----
58+
59+
Rust::
60+
+
61+
[source,rust]
62+
----
63+
use reqwest;
64+
65+
#[tokio::main]
66+
async fn main() -> Result<(), Box<dyn std::error::Error>> {
67+
let client = reqwest::Client::new();
68+
let resp = client
69+
.post("https://cloud.typedb.com/api/auth")
70+
.header(reqwest::header::AUTHORIZATION, "Basic {CLIENT_ID}:{CLIENT_SECRET}")
71+
.send().await;
72+
Ok(())
73+
}
74+
----
75+
====
76+
The response body will be your access token.
77+
+
78+
[NOTE]
79+
====
80+
For security, your access token will expire after 1 hour.
81+
====
82+
. Make an API request to list clusters in the project you selected for your API token.
83+
The example below targets the `default` project in an organization called `my-org`.
84+
You will use the access token you generated in the previous step to authenticate this request.
85+
+
86+
[tabs]
87+
====
88+
curl::
89+
+
90+
[source,console]
91+
----
92+
curl --request GET \
93+
--url https://cloud.typedb.com/api/org/ORG_ID/projects/PROJECT_ID/clusters \
94+
--header 'Authorization: Bearer {ACCESS-TOKEN}'
95+
----
96+
97+
Python::
98+
+
99+
[source,python]
100+
----
101+
import requests
102+
103+
url = "https://cloud.typedb.com/api/org/my-org/projects/default/clusters"
104+
105+
headers = {
106+
"Authorization": "Bearer {ACCESS-TOKEN}"
107+
}
108+
109+
response = requests.get(url, headers=headers)
110+
----
111+
112+
Rust::
113+
+
114+
[source,rust]
115+
----
116+
use reqwest;
117+
118+
#[tokio::main]
119+
async fn main() -> Result<(), Box<dyn std::error::Error>> {
120+
let client = reqwest::Client::new();
121+
let resp = client
122+
.get("https://cloud.typedb.com/api/org/my-org/projects/default/clusters")
123+
.header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
124+
.send().await;
125+
Ok(())
126+
}
127+
----
128+
====
129+
It will return information about the clusters in a JSON format, as below
130+
+
131+
[source,json]
132+
----
133+
[
134+
{
135+
"id":"my-cluster",
136+
"serverCount":1,
137+
"storageSizeGB":10,
138+
"isFree":true,
139+
"status":"running",
140+
"createdAt":1738256490070,
141+
"organizationID":"my-org",
142+
"projectID":"default",
143+
"version":"3.0.5",
144+
"provider":"gcp",
145+
"region":"europe-west2",
146+
"machineType":"c2d-highcpu-2",
147+
"storageType":"standard-rwo",
148+
"servers": [
149+
{
150+
"address": "abc123-0.cluster.typedb.com:80",
151+
"status": "running"
152+
}
153+
]
154+
}
155+
]
156+
----
157+
158+
== Next Steps
159+
160+
Now that you know how to list the clusters in your project from the API,
161+
you can explore TypeDB Cloud further, either through further API use or back on the website.
162+
163+
[cols-2]
164+
--
165+
.https://cloud.typedb.com[TypeDB Cloud,window=_blank]
166+
[.clickable]
167+
****
168+
Head back to TypeDB Cloud to keep exploring there.
169+
****
170+
171+
.xref:{page-version}@manual::cloud/api/reference.adoc[]
172+
[.clickable]
173+
****
174+
View the API reference for more detail on what you can do with it.
175+
****
176+
--

0 commit comments

Comments
 (0)