HTTP requests

🚧

JanusGraph Deprecation

As of September 2019, Compose will soon no longer support JanusGraph on the platform. Provisioning of new JanusGraph deployments is disabled.

HTTP Request access

HTTP Requests should be sent to the HTTPS endpoint. This endpoint information is available on the deployment's overview page under HTTPS Connections String

To access JanusGraph with a HTTP request you need to simply use the HTTP POST method with the endpoint and send a JSON formatted document with a single key "gremlin" that has a value of the Gremlin query you wish to send.

{
    "gremlin": "a gremlin query would go here"
}

Gremlin is an extensive traversal language but a program in it can also be as simple as "1+1". To pass that as a script in curl command requires would involve posting: '{"gremlin" : "1+1" }' as the data part of a POST request.

An optional "bindings" dictionary can be provided with a map of variables that is available to the gremlin script. If you're sending the same script several times to the server, it's recommended to use variables within your gremlin script and set them in the "bindings" dictionary. This helps with performance as the server won't have to recompile the gremlin script and, simply, inject the variables.

Additional information about the HTTP protocol can be found in the Connecting via REST section of the Apache Tinkerpop Documentation

To send this Gremlin script to the endpoint, you need to be authenticated. There are two ways to be authenticated with HTTP request access: Basic authentication and token authentication.

Basic Authentication

Basic authentication sends your username and password with the request. For one-off queries, it is reasonable, but any more than that and you begin loading the server with the complexity of doing the password exchange and validation. With curl you can pass the username and password with a -u option like so:

$ curl -XPOST -d '{"gremlin" : "1+1" }' "https://portal91-0.ianuspater.compose-3.composedb.com:17916" -u admin:PASSWORDHERE

You can also embed the username and password in the endpoint URL.

Token Authentication

To do efficient HTTP requests, you can obtain a session token from another endpoint. This token is passed in the header for all subsequent requests and is quick to check. If you are doing any more than one call on the HTTP endpoint, we recommend you use this process. The connection strings will already include the call needed to obtain the token as a curl command:

$ curl -XGET "https://admin:[email protected]:17916/session"
{"token": "YWRtaW46MTQ5NjkyODM1NDgzMzpWYXlxMERsMWs0VmltdGo3WUpzMEwtN3prUi00TGxZR3J6LXZnbDVmN3lnPQ=="}
$

We've shown the returned JSON result. Extract the token value and then include it as the Authorization header in a request

$ curl -XPOST -H "Authorization: Token YWRtaW46MTQ5NjkyODM1NDgzMzpWYXlxMERsMWs0VmltdGo3WUpzMEwtN3prUi00TGxZR3J6LXZnbDVmN3lnPQ==" -d '{"gremlin" : "1+1" }' "https://portal91-0.ianuspater.compose-3.composedb.com:17916"

If you are doing this from the shell and you have the jq command available, then you can set an environment variable running a command like this:

$ export JGTOKEN=`curl -s -XGET "https://admin:[email protected]:17916/session" | jq -r .token`

And then run requests like this:

$ curl -XPOST -H "Authorization: Token $JGTOKEN" -d '{"gremlin" : "1+1" }' "https://portal91-0.ianuspater.compose-3.composedb.com:17916"

HTTP JSON responses

Responses to queries follow are in the form of a JSON document with a request id value, a status object, and a result object. Here is an example of a response:

{
  "requestId": "1bf4d1d4-eba4-484f-a94b-3cfa85df3448",
  "status": {
    "message": "",
    "code": 200,
    "attributes": {}
  },
  "result": {
    "data": [
      {
        "god1": "hercules",
        "god2": "nemean"
      },
      {
        "god1": "hercules",
        "god2": "hydra"
      }
    ],
    "meta": {}
  }
}

The requestId is a unique identifier for the request. The status contains a readable message, a HTTP status style code and other attributes of the reported status. The result contains a data object which is structured according to whatever the executed Gremlin code returns and a meta section for any extra information that is outside the scope of the result data.

Still Need Help?

If this article didn't solve things, summon a human and get some help!