Skip to content

Commit 698af77

Browse files
farostfarost
authored
HTTP Endpoint documentation (#930)
## Goal Introduce HTTP API documentation to allow users to use the new TypeDB HTTP Endpoint starting from TypeDB 3.2.0-rc0. ## Implementation This is the first version of the docs, and they can be extended and enhanced in terms of the UX in the near future. Add: * HTTP "driver" docs with general description, setup and configuration guides, version compatibility, and the full API reference. * Code snippets for basic operations in Manuals: database and user management, working with transactions. * New server configuration options in Manual. Fix: * Small typos. * Invalid driver usage examples.
1 parent 2243037 commit 698af77

40 files changed

+2166
-28
lines changed

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

Lines changed: 1334 additions & 0 deletions
Large diffs are not rendered by default.

‎drivers/modules/ROOT/pages/http/index.adoc

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
= HTTP Endpoint
2+
3+
The TypeDB HTTP endpoint can be used to perform database management, user management, transaction management, and querying operations through HTTP.
4+
5+
== Server configuration
6+
7+
TypeDB server by runs both a gRPC (standard for most of the client applications) and an HTTP endpoint by default. Both endpoints have common authentication and xref:{page-version}@manual::configure/encryption.adoc[encryption settings]. Additionally, it is possible to disable the HTTP endpoint and change its default port.
8+
9+
[NOTE]
10+
====
11+
HTTP and gRPC ports must be different.
12+
====
13+
14+
Please visit xref:{page-version}@manual::configure/server.adoc#_command_line_arguments[Server configuration] for the configuration specification.
15+
16+
== Access the API
17+
18+
[#_authentication]
19+
=== Authentication
20+
21+
Mostly all methods require Token-based authorization. These temporary tokens can be generated through a xref:{page-version}@drivers::http/api-reference.adoc#_sign_in[`POST` request to `localhost:8000/v1/signin`]. Provide your TypeDB user credentials in the request's body.
22+
23+
Change the xref:{page-version}@manual::configure/server.adoc#_command_line_arguments[`server.authentication.token_ttl_seconds`] parameter in the server's configuration to modify the time the tokens will remain valid before a new sign in request is required.
24+
25+
=== Encryption
26+
27+
If xref:{page-version}@manual::configure/encryption.adoc[server encryption] is set up, its settings are also applied to the HTTP endpoint, and the endpoint access will be additionally protected. Visit the xref:{page-version}@manual::configure/server.adoc#_encryption[server configuration] page for more details.
28+
29+
=== CORS
30+
31+
The default permissive (allowing all headers, methods, and origins) CORS layer is set up.
32+
33+
== Set up databases and users
34+
35+
See xref:{page-version}@drivers::http/api-reference.adoc[] to access available database and user management methods.
36+
37+
[#_run_queries]
38+
== Run queries
39+
40+
=== Understanding query answers
41+
42+
The TypeDB HTTP endpoint supports all types of xref:{page-version}@manual::queries/transactions.adoc[transactions] and xref:{page-version}@manual::queries/index.adoc[queries]. The common xref:{page-version}@manual::queries/answers.adoc[query answer type], a list of concept rows, is represented in the HTTP endpoint like the following document:
43+
44+
.Concept rows answer
45+
[%collapsible]
46+
====
47+
Each successful query response contains a query type, an answer type, an optional warning message, and the list of answers containing concepts (if applicable).
48+
49+
The `answers` field contains a list of documents with variables as keys and concepts as values. Each concept contains a `kind` field for unambiguous parsing. Each type has a label, and each instance has an optional description of its type, if the specific query option (`includeInstanceTypes`) is enabled. See all the possible concept variants below.
50+
51+
include::{page-version}@drivers:resources:partial$http-api/responses/query-concept-rows-example.json.adoc[]
52+
====
53+
54+
The result above can be achieved in two different ways.
55+
56+
=== Manual transaction management
57+
58+
This will except you to manually open, close, and commit transactions used for querying.
59+
60+
Open a transaction using a `POST` request `/v1/transactions/open`. Provide an authorization token in the header (see xref:{page-version}@drivers::http/index.adoc#_authentication[authentication] above) and a JSON body, containing information about the target database and required transaction type:
61+
62+
[source,json]
63+
----
64+
{
65+
"databaseName": "typedb",
66+
"transactionType": "read"
67+
}
68+
----
69+
70+
[NOTE]
71+
====
72+
Schema transactions have an exclusive lock on the database and prevent other transactions from opening. If you don't close a schema transaction and lose its ID, it will be closed automatically based on the transaction timeout specified in the request (this parameter can be added to the request above):
73+
[source,json]
74+
----
75+
"transactionOptions": {
76+
"transactionTimeoutMillis": <integer>
77+
}
78+
----
79+
====
80+
81+
If everything is correct, you will receive a response containing a body like:
82+
[source,json]
83+
----
84+
{
85+
"transactionId": "e1f8583c-2a03-4aac-a260-ec186369e86f"
86+
}
87+
----
88+
89+
Then, send a `POST` query request to `v1/transactions/e1f8583c-2a03-4aac-a260-ec186369e86f/query` with the same authorization token in the header and the following JSON body included:
90+
[source,json]
91+
----
92+
{
93+
"query": "<your TypeQL query>",
94+
"queryOptions": {
95+
"includeInstanceTypes": true
96+
}
97+
}
98+
----
99+
100+
Don't forget to close the transaction when the work is done.
101+
102+
=== One-shot query
103+
104+
To avoid manual transaction management, a one-shot query endpoint can be used. It opens and automatically closes or commits a transaction for each query sent.
105+
106+
Send a single `POST` request to `/v1/query`. Provide an authorization token in the header (see xref:{page-version}@drivers::http/index.adoc#_authentication[authentication] above) and the following body containing information about the target database, transaction type required, query, and optional options:
107+
[source,json]
108+
----
109+
{
110+
"databaseName": "typedb",
111+
"transactionType": "read",
112+
"query": "<your TypeQL query>",
113+
"queryOptions": {
114+
"includeInstanceTypes": true
115+
},
116+
"commit": false
117+
}
118+
----
119+
120+
With this, you don't need to worry about forgotten transactions.
121+
122+
=== Running big queries
123+
124+
The current version of the HTTP endpoint does not support query answer streaming. Unlike in gRPC, the query results will be fully consumed before an initial answer is received on the client side, and the whole list of concept rows or documents will be returned in a single response.
125+
126+
While this mechanism will be enhanced in the future, for safety purposes, please use a special query option `answerCountLimit` to limit the amount of produced results and avoid too long query execution. The default value of ten thousand answers can be extended if you are ready for the consequences.
127+
128+
If this limit is hit:
129+
130+
- Read queries will return `206 Partial Content` with all the answers
131+
processed;
132+
- Write queries will stop their execution with an error, and the transaction will be closed without preserving intermediate results.
133+
134+
[NOTE]
135+
====
136+
This behaviour will be changed in the next stable version of TypeDB:
137+
138+
- Write queries will be fully executed, and their changes can be committed. The results will be returned with the `206 Partial Content` code.
139+
====
140+
141+
For example:
142+
Sending a request to `/v1/transactions/:transaction-id/query` with the following body:
143+
144+
[source,json]
145+
----
146+
{
147+
"query": "match $p isa person, has $n; delete has $n of $p;",
148+
"queryOptions": {
149+
"answerCountLimit": 1
150+
}
151+
}
152+
----
153+
154+
Can lead to: `400 Bad Request`
155+
156+
[source,json]
157+
----
158+
{
159+
"code": "HSR13",
160+
"message": "[TSV17] Write query results limit (1) exceeded, and the transaction is aborted. Retry with an extended limit or break the query into multiple smaller queries to achieve the same result.\n[HSR13] Transaction error."
161+
}
162+
----
163+
164+
== Next Steps
165+
166+
[cols-2]
167+
--
168+
.xref:{page-version}@manual::configure/server.adoc[]
169+
[.clickable]
170+
****
171+
Explore more TypeDB server's and its HTTP endpoint's configuration options.
172+
****
173+
174+
.xref:{page-version}@drivers::http/api-reference.adoc[]
175+
[.clickable]
176+
****
177+
View the API reference for more detail on how to communicate with your TypeDB server.
178+
****
179+
--
180+
181+
[#_version_compatibility]
182+
== Version Compatibility
183+
184+
[cols="^.^2,^.^2,^.^2",options="header"]
185+
|===
186+
| HTTP API version | TypeDB | TypeDB Community Edition
187+
188+
| v1
189+
| 3.2.0+
190+
| 3.2.0+
191+
|===

‎drivers/modules/ROOT/pages/index.adoc

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,12 @@ Welcome to the TypeDB driver documentation!
88

99
== Introduction
1010

11-
To build an application on TypeDB, we need to use a TypeDB language driver to communicate with the server.
11+
To build an application on TypeDB, we need to use a TypeDB driver to communicate with the server. TypeDB servers expose two external endpoints:
1212

13-
[#_typedb_drivers]
14-
TypeDB drivers implement the https://github.com/typedb/typedb-protocol[TypeDB RPC protocol,window=_blank] and provide language-specific native APIs.
15-
They are available for some of the most popular programming languages: Rust, Python, and Java.
16-
Drivers for Node.js, C#, C++, and C are soon to be published.
13+
- https://github.com/typedb/typedb-protocol[TypeDB RPC,window=_blank] (used for all the officially supported programming languages);
14+
- xref:{page-version}@drivers::http/index.adoc[TypeDB HTTP] (a more accessible API for other tools, including web applications and languages with a reduced RPC support).
15+
16+
Drivers with language-specific native APIs are available for some of the most popular programming languages: Rust, Python, and Java. Drivers for Node.js, C#, C++, and C are soon to be published.
1717

1818
[#_driver_api]
1919
== Rust driver
@@ -209,3 +209,20 @@ TypeDB servers accept client connections via gRPC based on the https://github.co
209209
The Java and Python drivers are implemented as wrappers on top of the Rust driver via an FFI interface.
210210
// The Node.js driver is implemented independently.
211211
====
212+
213+
== HTTP endpoint
214+
215+
[cols-3]
216+
--
217+
.xref:{page-version}@drivers::http/index.adoc[Overview]
218+
[.clickable]
219+
****
220+
Basic information, FAQ, and version compatibility.
221+
****
222+
223+
.xref:{page-version}@drivers::http/api-reference.adoc[API reference]
224+
[.clickable]
225+
****
226+
A complete API reference.
227+
****
228+
--

‎drivers/modules/ROOT/partials/nav.adoc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414
** xref:{page-version}@drivers::java/tutorial.adoc[Tutorial]
1515
** xref:drivers::java/api-reference.adoc[API reference]
1616
17+
* xref:{page-version}@drivers::http/index.adoc[]
18+
** xref:{page-version}@drivers::http/api-reference.adoc[API reference]
19+
1720
// * xref:{page-version}@drivers::nodejs/index.adoc[]
1821
// ** xref:{page-version}@drivers::nodejs/tutorial.adoc[Tutorial]
1922
// ** xref:drivers::nodejs/api-reference.adoc[API reference]

‎drivers/modules/resources/partials/http-api/requests/post-users.json.adoc

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

‎drivers/modules/resources/partials/http-api/requests/put-users.json.adoc

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

‎drivers/modules/resources/partials/http-api/requests/query-concept-documents-example.json.adoc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[source,json]
2+
----
3+
{
4+
"databaseName": "test",
5+
"transactionType": "read",
6+
"query": "match $entity isa $entity-type, has $attribute-type $attribute; $relation isa $relation-type, links ($entity); $relation-type relates $role-type; fetch { 'entity type': $entity-type, 'relation type': $relation-type, 'entity attributes': { $entity.* }, 'sub query': [ match let $value = $attribute; fetch { 'value': $value }; ] };"
7+
}
8+
----

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[source,json]
2+
----
3+
{
4+
"databaseName": "test",
5+
"transactionType": "read",
6+
"query": "match $entity isa $entity-type, has $attribute-type $attribute; $relation isa $relation-type, links ($entity); $relation-type relates $role-type; let $value = $attribute;",
7+
"queryOptions": {
8+
"includeInstanceTypes": true
9+
}
10+
}
11+
----

‎drivers/modules/resources/partials/http-api/requests/query.json.adoc

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[source,json]
2+
----
3+
{
4+
"query": string,
5+
"commit": boolean, // optional
6+
"databaseName": string,
7+
"transactionType": "read" | "write" | "schema",
8+
"transactionOptions": { // optional
9+
"schemaLockAcquireTimeoutMillis": integer, // optional
10+
"transactionTimeoutMillis": integer // optional
11+
},
12+
"queryOptions": { // optional
13+
"includeInstanceTypes": boolean, // optional
14+
"answerCountLimit": integer // optional
15+
}
16+
}
17+
----

‎drivers/modules/resources/partials/http-api/requests/signin.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+
"username": string,
5+
"password": string
6+
}
7+
----

0 commit comments

Comments
 (0)