HTTP Endpoint
The TypeDB HTTP endpoint can be used to perform database management, user management, transaction management, and querying operations through HTTP.
Server configuration
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 encryption settings. Additionally, it is possible to disable the HTTP endpoint and change its default port.
|
HTTP and gRPC ports must be different. |
Please visit Server configuration for the configuration specification.
Access the API
Authentication
Mostly all methods require Token-based authorization. These temporary tokens can be generated through a POST request to localhost:8000/v1/signin. Provide your TypeDB user credentials in the request’s body.
Change the 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.
Encryption
If server encryption is set up, its settings are also applied to the HTTP endpoint, and the endpoint access will be additionally protected. Visit the server configuration page for more details.
Set up databases and users
See TypeDB HTTP API Reference to access available database and user management methods.
Run queries
Understanding query answers
The TypeDB HTTP endpoint supports all types of transactions and queries. The common query answer type, a list of concept rows, is represented in the HTTP endpoint like the following document:
Concept rows answer
Each successful query response contains a query type, an answer type, an optional warning message, and the list of answers containing concepts (if applicable).
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.
{
"queryType": "read",
"answerType": "conceptRows",
"answers": [
{
"entity": {
"kind": "entity",
"iid": "0x1e00000000000000000001",
"type": {
"kind": "entityType",
"label": "person"
}
},
"role-type": {
"kind": "roleType",
"label": "parentship:parent"
},
"relation": {
"kind": "relation",
"iid": "0x1f00000000000000000000",
"type": {
"kind": "relationType",
"label": "parentship"
}
},
"relation-type": {
"kind": "relationType",
"label": "parentship"
},
"attribute-type": {
"kind": "attributeType",
"label": "name",
"valueType": "string"
},
"entity-type": {
"kind": "entityType",
"label": "person"
},
"value": {
"kind": "value",
"value": "John",
"valueType": "string"
},
"attribute": {
"kind": "attribute",
"value": "John",
"valueType": "string",
"type": {
"kind": "attributeType",
"label": "name",
"valueType": "string"
}
}
}
],
"warning": null
}The result above can be achieved in two different ways.
Manual transaction management
This will except you to manually open, close, and commit transactions used for querying.
Open a transaction using a POST request /v1/transactions/open. Provide an authorization token in the header (see authentication above) and a JSON body, containing information about the target database and required transaction type:
{
"databaseName": "typedb",
"transactionType": "read"
}|
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): |
If everything is correct, you will receive a response containing a body like:
{
"transactionId": "e1f8583c-2a03-4aac-a260-ec186369e86f"
}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:
{
"query": "<your TypeQL query>",
"queryOptions": {
"includeInstanceTypes": true
}
}Don’t forget to close the transaction when the work is done.
One-shot query
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.
Send a single POST request to /v1/query. Provide an authorization token in the header (see authentication above) and the following body containing information about the target database, transaction type required, query, and optional options:
{
"databaseName": "typedb",
"transactionType": "read",
"query": "<your TypeQL query>",
"queryOptions": {
"includeInstanceTypes": true
},
"commit": false
}With this, you don’t need to worry about forgotten transactions.
Running big queries
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.
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.
If this limit is hit:
-
Read queries will return
206 Partial Contentwith all the answers processed; -
Write queries will stop their execution with an error, and the transaction will be closed without preserving intermediate results.
|
This behaviour will be changed in the next stable version of TypeDB:
|
For example:
Sending a request to /v1/transactions/:transaction-id/query with the following body:
{
"query": "match $p isa person, has $n; delete has $n of $p;",
"queryOptions": {
"answerCountLimit": 1
}
}Can lead to: 400 Bad Request
{
"code": "HSR13",
"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."
}