EdgeQL over HTTP​

.md

Copy page

Setup​

In order to set up HTTP access to the database add the following to the schema:

using extension edgeql_http;

Then create a new migration and apply it using gel migration create and gel migrate, respectively.

Your instance can now receive EdgeQL queries over HTTP at https://<hostname>:<port>/branch/<branch-name>/edgeql.

AuthenticationAdded in v4.0​

By default, the HTTP endpoint uses cfg::Password based authentication, in which HTTP Basic Authentication is used to provide a Gel username and password.

This is configurable, however: the HTTP endpoint's authentication mechanism can be configured by adjusting which cfg::AuthMethod applies to the SIMPLE_HTTP cfg::ConnectionTransport.

If cfg::JWT is used, the requests should contain these headers:

• X-EdgeDB-User: The Gel username.

• Authorization: The JWT authorization token prefixed by Bearer.

If cfg::Trust is used, no authentication is done at all. This is not generally recommended, but can be used to recover the pre-4.0 behavior:

db> configure instance insert cfg::Auth {
...     priority := -1,
...     method := (insert cfg::Trust { transports := "SIMPLE_HTTP" }),
... };
OK: CONFIGURE INSTANCE

To authenticate to your Gel Cloud instance, first create a secret key using the Gel Cloud UI or gel cloud secretkey create. Use the secret key as your token with the bearer authentication method. Here is an example showing how you might send the query select Person {*}; using cURL:

$ 
  
  

curl -G https://<cloud-instance-host>:<cloud-instance-port>/branch/main/edgeql \
 -H "Authorization: Bearer <secret-key> \
 --data-urlencode "query=select Person {*};"

Querying​

Gel supports GET and POST methods for handling EdgeQL over HTTP protocol. Both GET and POST methods use the following fields:

• query - contains the EdgeQL query string

• variables- contains a JSON object where the keys are the parameter names from the query and the values are the arguments to be used in this execution of the query. Optional

• globals- contains a JSON object where the keys are the fully qualified global names and the values are the desired values for those globals. Optional

• config - contains a JSON object where the keys are configuration option names and the values are the desired values for those configs. Optional. Added in 7.0.

The protocol supports HTTP Keep-Alive.

{
  "query": "select Person {*} filter .name = <str>$name;",
  "variables": { "name": "John" },
  "globals": { "default::global_name": "value" },
  "config": { "default_transaction_isolation": "RepeatableRead" }
}

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "John"
    }
  ],
  "error": {
    "message": "Error message",
    "type": "ErrorType",
    "code": 123456
  }
}