Skip to content

Commit 203e0c6

Browse files
farostfarost
authored
Update HTTP endpoint's API reference for the 3.2.0 release (#935)
## Goal Add new schema retrieval and version API references and adjust outdated query response examples. ## Implementation Add schema retrieval and version API references. Update query row examples to align with the updated server's response format.
1 parent 679fc87 commit 203e0c6

File tree

5 files changed

+273
-41
lines changed

5 files changed

+273
-41
lines changed

‎drivers/modules/ROOT/pages/http/api-reference.adoc

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,75 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
118118
----
119119
// end::token-example[]
120120

121+
== Server information
122+
123+
=== Version
124+
125+
Get the server's distribution and version information.
126+
127+
[cols="h,3a"]
128+
|===
129+
| Token required | No
130+
| Method | `GET`
131+
| URL | `/v1/version`
132+
| Request body | None
133+
| Request headers | None
134+
|===
135+
136+
*Responses:*
137+
138+
include::{page-version}@drivers:resources:partial$http-api/responses/details.adoc[tags="200-version"]
139+
140+
*Example request:*
141+
142+
[tabs]
143+
====
144+
curl::
145+
+
146+
[source,console]
147+
----
148+
curl --request GET \
149+
--url http://0.0.0.0:8000/v1/version
150+
----
151+
152+
Python::
153+
+
154+
[source,python]
155+
----
156+
import requests
157+
158+
url = "http://0.0.0.0:8000/v1/version"
159+
160+
response = requests.get(url)
161+
----
162+
163+
Rust::
164+
+
165+
[source,rust]
166+
----
167+
use reqwest;
168+
169+
#[tokio::main]
170+
async fn main() -> Result<(), Box<dyn std::error::Error>> {
171+
let client = reqwest::Client::new();
172+
let resp = client
173+
.get("http://0.0.0.0:8000/v1/version")
174+
.send().await;
175+
Ok(())
176+
}
177+
----
178+
====
179+
180+
*Example response:*
181+
182+
[source]
183+
----
184+
{
185+
"distribution": "TypeDB",
186+
"version": "3.2.0"
187+
}
188+
----
189+
121190
== Databases
122191

123192
=== Get databases
@@ -376,6 +445,134 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
376445
----
377446
====
378447

448+
=== Get database's schema
449+
450+
Retrieve a full schema text as a valid TypeQL define query string. This includes function definitions.
451+
452+
[cols="h,3a"]
453+
|===
454+
| Token required | Yes
455+
| Method | `GET`
456+
| URL | `/v1/databases/DATABASE_NAME/schema`
457+
| Request body | None
458+
| Request headers | `Authorization: Bearer ACCESS_TOKEN`
459+
|===
460+
461+
*Responses:*
462+
463+
include::{page-version}@drivers:resources:partial$http-api/responses/details.adoc[tags="200-database-schema,400,401,404"]
464+
465+
*Example request:*
466+
467+
[tabs]
468+
====
469+
curl::
470+
+
471+
[source,console]
472+
----
473+
474+
curl --request GET \
475+
--url http://0.0.0.0:8000/v1/databases/DATABASE_NAME/schema \
476+
--header 'Authorization: Bearer {ACCESS-TOKEN}'
477+
----
478+
479+
Python::
480+
+
481+
[source,python]
482+
----
483+
import requests
484+
485+
url = "http://0.0.0.0:8000/v1/databases/DATABASE_NAME/schema"
486+
487+
headers = {
488+
"Authorization": "Bearer {ACCESS-TOKEN}"
489+
}
490+
491+
response = requests.get(url, headers=headers)
492+
----
493+
494+
Rust::
495+
+
496+
[source,rust]
497+
----
498+
use reqwest;
499+
500+
#[tokio::main]
501+
async fn main() -> Result<(), Box<dyn std::error::Error>> {
502+
let client = reqwest::Client::new();
503+
let resp = client
504+
.get("http://0.0.0.0:8000/v1/databases/DATABASE_NAME/schema")
505+
.header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
506+
.send().await;
507+
Ok(())
508+
}
509+
----
510+
====
511+
512+
=== Get database's type schema
513+
514+
Retrieve the types in the schema as a valid TypeQL define query string.
515+
516+
[cols="h,3a"]
517+
|===
518+
| Token required | Yes
519+
| Method | `GET`
520+
| URL | `/v1/databases/DATABASE_NAME/type-schema`
521+
| Request body | None
522+
| Request headers | `Authorization: Bearer ACCESS_TOKEN`
523+
|===
524+
525+
*Responses:*
526+
527+
include::{page-version}@drivers:resources:partial$http-api/responses/details.adoc[tags="200-database-schema,400,401,404"]
528+
529+
*Example request:*
530+
531+
[tabs]
532+
====
533+
curl::
534+
+
535+
[source,console]
536+
----
537+
538+
curl --request GET \
539+
--url http://0.0.0.0:8000/v1/databases/DATABASE_NAME/type-schema \
540+
--header 'Authorization: Bearer {ACCESS-TOKEN}'
541+
----
542+
543+
Python::
544+
+
545+
[source,python]
546+
----
547+
import requests
548+
549+
url = "http://0.0.0.0:8000/v1/databases/DATABASE_NAME/type-schema"
550+
551+
headers = {
552+
"Authorization": "Bearer {ACCESS-TOKEN}"
553+
}
554+
555+
response = requests.get(url, headers=headers)
556+
----
557+
558+
Rust::
559+
+
560+
[source,rust]
561+
----
562+
use reqwest;
563+
564+
#[tokio::main]
565+
async fn main() -> Result<(), Box<dyn std::error::Error>> {
566+
let client = reqwest::Client::new();
567+
let resp = client
568+
.get("http://0.0.0.0:8000/v1/databases/DATABASE_NAME/type-schema")
569+
.header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
570+
.send().await;
571+
Ok(())
572+
}
573+
----
574+
====
575+
379576
== Users
380577

381578
=== Get users

‎drivers/modules/resources/partials/http-api/responses/details.adoc

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,14 @@ include::{page-version}@drivers:resources:partial$http-api/responses/get-databas
1414
====
1515
// end::200-databases[]
1616

17+
// tag::200-version[]
18+
.200: OK
19+
[%collapsible]
20+
====
21+
include::{page-version}@drivers:resources:partial$http-api/responses/version.json.adoc[]
22+
====
23+
// end::200-version[]
24+
1725
// tag::200-database[]
1826
.200: OK
1927
[%collapsible]
@@ -22,6 +30,14 @@ include::{page-version}@drivers:resources:partial$http-api/responses/get-databas
2230
====
2331
// end::200-database[]
2432

33+
// tag::200-database-schema[]
34+
.200: OK
35+
[%collapsible]
36+
====
37+
include::{page-version}@drivers:resources:partial$http-api/responses/get-database-schema.adoc[]
38+
====
39+
// end::200-database-schema[]
40+
2541
// tag::200-users[]
2642
.200: OK
2743
[%collapsible]

‎drivers/modules/resources/partials/http-api/responses/get-database-schema.adoc

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.If schema is defined
2+
[source,bash]
3+
----
4+
"define <statements>;"
5+
----
6+
.If schema is not defined
7+
[source,bash]
8+
----
9+
""
10+
----

‎drivers/modules/resources/partials/http-api/responses/query-concept-rows-example.json.adoc

Lines changed: 43 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -5,52 +5,54 @@
55
"answerType": "conceptRows",
66
"answers": [
77
{
8-
"entity": {
9-
"kind": "entity",
10-
"iid": "0x1e00000000000000000001",
11-
"type": {
12-
"kind": "entityType",
13-
"label": "person"
14-
}
15-
},
16-
"role-type": {
17-
"kind": "roleType",
18-
"label": "parentship:parent"
19-
},
20-
"relation": {
21-
"kind": "relation",
22-
"iid": "0x1f00000000000000000000",
23-
"type": {
8+
"data": {
9+
"entity": {
10+
"kind": "entity",
11+
"iid": "0x1e00000000000000000001",
12+
"type": {
13+
"kind": "entityType",
14+
"label": "person"
15+
}
16+
},
17+
"role-type": {
18+
"kind": "roleType",
19+
"label": "parentship:parent"
20+
},
21+
"relation": {
22+
"kind": "relation",
23+
"iid": "0x1f00000000000000000000",
24+
"type": {
25+
"kind": "relationType",
26+
"label": "parentship"
27+
}
28+
},
29+
"relation-type": {
2430
"kind": "relationType",
2531
"label": "parentship"
26-
}
27-
},
28-
"relation-type": {
29-
"kind": "relationType",
30-
"label": "parentship"
31-
},
32-
"attribute-type": {
33-
"kind": "attributeType",
34-
"label": "name",
35-
"valueType": "string"
36-
},
37-
"entity-type": {
38-
"kind": "entityType",
39-
"label": "person"
40-
},
41-
"value": {
42-
"kind": "value",
43-
"value": "John",
44-
"valueType": "string"
45-
},
46-
"attribute": {
47-
"kind": "attribute",
48-
"value": "John",
49-
"valueType": "string",
50-
"type": {
32+
},
33+
"attribute-type": {
5134
"kind": "attributeType",
5235
"label": "name",
5336
"valueType": "string"
37+
},
38+
"entity-type": {
39+
"kind": "entityType",
40+
"label": "person"
41+
},
42+
"value": {
43+
"kind": "value",
44+
"value": "John",
45+
"valueType": "string"
46+
},
47+
"attribute": {
48+
"kind": "attribute",
49+
"value": "John",
50+
"valueType": "string",
51+
"type": {
52+
"kind": "attributeType",
53+
"label": "name",
54+
"valueType": "string"
55+
}
5456
}
5557
}
5658
}

‎drivers/modules/resources/partials/http-api/responses/version.json.adoc

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[source,json]
2+
----
3+
{
4+
"distribution": string,
5+
"version": string
6+
}
7+
----

0 commit comments

Comments
 (0)