Raw HTTP

It’s also possible to interact with Dgraph directly via its HTTP endpoints. This allows clients to be built for languages that don’t have access to a working gRPC implementation.

In the examples shown here, regular command line tools such as curl and jq are used. However, the real intention here is to show other programmers how they could implement a client in their language on top of the HTTP API.

For an example of how to build a client on top of gRPC, refer to the implementation of the Go client.

Similar to the Go client example, we use a bank account transfer example.

Create the Client

A client built on top of the HTTP API will need to track three pieces of state for each transaction.

1. A start timestamp (start_ts). This uniquely identifies a transaction, and doesn’t change over the transaction lifecycle.

2. The set of keys modified by the transaction (keys). This aids in transaction conflict detection.

   Every mutation would send back a new set of keys. The client must merge them with the existing set. Optionally, a client can de-dup these keys while merging.

3. The set of predicates modified by the transaction (preds). This aids in predicate move detection.

   Every mutation would send back a new set of preds. The client must merge them with the existing set. Optionally, a client can de-dup these keys while merging.

Alter the DQL Schema

You may need to alter the DQL schema to declare predicate types, to add predicate search indexes and to declare the predicates expected in entities of specific type.

Update the DQL schema is done by posting schema data to the /alter endpoint:

curl "localhost:8080/alter" --silent --request POST \
  --data $'
name: string @index(term) .
release_date: datetime @index(year) .
revenue: float .
running_time: int .
starring: [uid] .
director: [uid] .

type Person {
  name
}

type Film {
  name
  release_date
  revenue
  running_time
  starring
  director
}
' | python -m json.tool 

Success response

{
    "data": {
        "code": "Success",
        "message": "Done"
    }
}

Error response

In case of errors, the API will reply with an error message such as:

{
    "errors": [
        {
            "extensions": {
                "code": "Error"
            },
            "message": "line 5 column 18: Invalid ending"
        }
    ]
}

Query current DQL schema

Obtain the DQL schema by issuing a DQL query on /query endpoint.

$ curl -X POST \
  -H "Content-Type: application/dql" \
  localhost:8080/query -d $'schema {}' | python -m json.tool

Start a transaction

Assume some initial accounts with balances have been populated. We now want to transfer money from one account to the other. This is done in four steps:

1. Create a new transaction.

2. Inside the transaction, run a query to determine the current balances.

3. Perform a mutation to update the balances.

4. Commit the transaction.

Starting a transaction doesn’t require any interaction with Dgraph itself. Some state needs to be set up for the transaction to use. The start_ts can initially be set to 0. keys can start as an empty set.

For both query and mutation if the start_ts is provided as a path parameter, then the operation is performed as part of the ongoing transaction. Otherwise, a new transaction is initiated.

Run a query

To query the database, the /query endpoint is used. Remember to set the Content-Type header to application/dql to ensure that the body of the request is parsed correctly.

To get the balances for both accounts:

$ curl -H "Content-Type: application/dql" -X POST localhost:8080/query -d $'
{
  balances(func: anyofterms(name, "Alice Bob")) {
    uid
    name
    balance
  }
}' | jq

The result should look like this:

{
  "data": {
    "balances": [
      {
        "uid": "0x1",
        "name": "Alice",
        "balance": "100"
      },
      {
        "uid": "0x2",
        "name": "Bob",
        "balance": "70"
      }
    ]
  },
  "extensions": {
    "server_latency": {
      "parsing_ns": 70494,
      "processing_ns": 697140,
      "encoding_ns": 1560151
    },
    "txn": {
      "start_ts": 4,
    }
  }
}

Notice that along with the query result under the data field is additional data in the extensions -> txn field. This data will have to be tracked by the client.

For queries, there is a start_ts in the response. This start_ts will need to be used in all subsequent interactions with Dgraph for this transaction, and so should become part of the transaction state.

Run a Mutation

Mutations can be done over HTTP by making a POST request to an Alpha’s /mutate endpoint. Now that we have the current balances, we need to send a mutation to Dgraph with the updated balances. If Bob transfers $10 to Alice, then the RDFs to send are:

<0x1> <balance> "110" .
<0x1> <dgraph.type> "Balance" .
<0x2> <balance> "60" .
<0x2> <dgraph.type> "Balance" .

Note that we have to refer to the Alice and Bob nodes by UID in the RDF format.

We now send the mutations via the /mutate endpoint. We need to provide our transaction start timestamp as a path parameter, so that Dgraph knows which transaction the mutation should be part of. We also need to set Content-Type header to application/rdf in order to specify that mutation is written in RDF format.

$ curl -H "Content-Type: application/rdf" -X POST localhost:8080/mutate?startTs=4 -d $'
{
  set {
    <0x1> <balance> "110" .
    <0x1> <dgraph.type> "Balance" .
    <0x2> <balance> "60" .
    <0x2> <dgraph.type> "Balance" .
  }
}
' | jq

The result:

{
  "data": {
    "code": "Success",
    "message": "Done",
    "uids": {}
  },
  "extensions": {
    "server_latency": {
      "parsing_ns": 50901,
      "processing_ns": 14631082
    },
    "txn": {
      "start_ts": 4,
      "keys": [
        "2ahy9oh4s9csc",
        "3ekeez23q5149"
      ],
      "preds": [
        "1-balance"
      ]
    }
  }
}

The result contains keys and predicates which should be added to the transaction state.

Committing the transaction

Finally, we can commit the transaction using the /commit endpoint. We need the start_ts we’ve been using for the transaction along with the list of keys and the list of predicates. If we had performed multiple mutations in the transaction instead of just one, then the keys and predicates provided during the commit would be the union of all keys and predicates returned in the responses from the /mutate endpoint.

The preds field is used to abort the transaction in cases where some of the predicates are moved. This field is not required and the /commit endpoint also accepts the old format, which was a single array of keys.

$ curl -X POST localhost:8080/commit?startTs=4 -d $'
{
  "keys": [
		"2ahy9oh4s9csc",
		"3ekeez23q5149"
	],
  "preds": [
    "1-balance"
	]
}' | jq

The result:

{
  "data": {
    "code": "Success",
    "message": "Done"
  },
  "extensions": {
    "txn": {
      "start_ts": 4,
      "commit_ts": 5
    }
  }
}

The transaction is now complete.

If another client were to perform another transaction concurrently affecting the same keys, then it’s possible that the transaction would not be successful. This is indicated in the response when the commit is attempted.

{
  "errors": [
    {
      "code": "Error",
      "message": "Transaction has been aborted. Please retry."
    }
  ]
}

In this case, it should be up to the user of the client to decide if they wish to retry the transaction.

Aborting the transaction

To abort a transaction, use the same /commit endpoint with the abort=true parameter while specifying the startTs value for the transaction.

$ curl -X POST "localhost:8080/commit?startTs=4&abort=true" | jq

The result:

{
  "code": "Success",
  "message": "Done"
}

Running read-only queries

You can set the query parameter ro=true to /query to set it as a read-only query.

$ curl -H "Content-Type: application/dql" -X POST "localhost:8080/query?ro=true" -d $'
{
  balances(func: anyofterms(name, "Alice Bob")) {
    uid
    name
    balance
  }
}

Running best-effort queries

You can set the query parameter be=true to /query to set it as a best-effort query.

$ curl -H "Content-Type: application/dql" -X POST "localhost:8080/query?be=true" -d $'
{
  balances(func: anyofterms(name, "Alice Bob")) {
    uid
    name
    balance
  }
}

Compression via HTTP

Dgraph supports gzip-compressed requests to and from Dgraph Alphas for /query, /mutate, and /alter.

Compressed requests: To send compressed requests, set the HTTP request header Content-Encoding: gzip along with the gzip-compressed payload.

Compressed responses: To receive gzipped responses, set the HTTP request header Accept-Encoding: gzip and Alpha will return gzipped responses.

Example of a compressed request via curl:

$ curl -X POST \
  -H 'Content-Encoding: gzip' \
  -H "Content-Type: application/rdf" \
  localhost:8080/mutate?commitNow=true --data-binary @mutation.gz

Example of a compressed request via curl:

$ curl -X POST \
  -H 'Accept-Encoding: gzip' \
  -H "Content-Type: application/dql" \
  localhost:8080/query -d $'schema {}' | gzip --decompress

Example of a compressed request and response via curl:

$ zcat query.gz # query.gz is gzipped compressed
{
  all(func: anyofterms(name, "Alice Bob")) {
    uid
    balance
  }
}

$ curl -X POST \
  -H 'Content-Encoding: gzip' \
  -H 'Accept-Encoding: gzip' \
  -H "Content-Type: application/dql" \
  localhost:8080/query --data-binary @query.gz | gzip --decompress

$ curl -X POST --compressed -H "Content-Type: application/dql" localhost:8080/query -d $'schema {}'

Run a query in JSON format

The HTTP API also accepts requests in JSON format. For queries you have the keys “query” and “variables”. The JSON format is required to set GraphQL Variables with the HTTP API.

This query:

{
  balances(func: anyofterms(name, "Alice Bob")) {
    uid
    name
    balance
  }
}

Should be escaped to this:

curl -H "Content-Type: application/json" localhost:8080/query -XPOST -d '{
    "query": "{\n balances(func: anyofterms(name, \"Alice Bob\")) {\n uid\n name\n balance\n }\n }"
}' | python -m json.tool | jq