GraphQL

Database is accessible through a GraphQL API which uses JWT tokens as an Authentication mechanism or the specified X-Hasura-Access-Key in the .env file (careful this is a master key).

JWT Request

To generate a JWT access token you need to send a POST request on /jwt/auth endpoint. POST request should include username and password of the user that wants to access the API. Depending on the role of the user permissions are different.

Example of a curl request (-k is for self-signed certificates):

curl -k -X POST -H "Content-Type: application/json" -d '{"username":$username, "password":$password}' https://url/jwt/auth

Successful request reply (200 status code):

{"access_token": "xxxxxxxxx"}

Failed request reply (401 status code):

{"error": "wrong credentials"}

Querying GraphQL

You can access the GraphQL API endpoint at /api/graphql. The schemas are auto-generated by Hasura so you can read their documentation on how to create queries for our database.

Examples

Query on bgp_updates table for all fields:

curl -k -X POST -H "Content-Type: application/json" -H "Authorization":"Bearer "$access_token https://url/api/graphql -d @query.json

Where query.json file includes:

{
"query":
"query {
  view_bgpupdates(limit: 10, order_by: {timestamp: desc}) {
    as_path
    communities
    handled
    hijack_key
    matched_prefix
    orig_path
    origin_as
    peer_asn
    prefix
    service
    timestamp
    type
  }
}"
}

Query on hijacks table for all fields:

curl -k -X POST -H "Content-Type: application/json" -H "Authorization":"Bearer "$access_token https://url/api/graphql -d @query.json

Where query.json file includes:

{
"query":
"query {
  view_hijacks(limit: 10, order_by: {time_last: desc}) {
    active
    comment
    configured_prefix
    hijack_as
    ignored
    dormant
    key
    mitigation_started
    num_asns_inf
    num_peers_seen
    outdated
    peers_seen
    peers_withdrawn
    prefix
    resolved
    seen
    time_detected
    time_ended
    time_last
    time_started
    timestamp_of_config
    type
    under_mitigation
    withdrawn
    community_annotation
    rpki_status
  }
}"
}

For subscriptions you need to use WebSockets.

GraphQL Console

You can enable GraphQL console in .env by setting HASURA_CONSOLE to true. Afterwards, you should configure nginx.conf to proxy to the console on a specific port and docker-compose.yaml to map the nginx container port to the supervisors.

Changes in nginx.conf to proxy hasura console to port 32000:

    server {
        listen 32000 ssl;
        resolver localhost;
        error_page 497  https://$host:$server_port$request_uri;

        location / {
            proxy_pass http://graphql:8080/;
            proxy_redirect off;
            proxy_http_version 1.1;
            proxy_set_header Host $host:$server_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header X-Forwarded-Ssl on;
        }

        ssl_certificate /etc/nginx/certs/cert.pem;
        ssl_certificate_key /etc/nginx/certs/key.pem;

        gzip on;
        gzip_proxied any;
        gzip_types
            text/css
            text/javascript
            text/xml
            text/plain
            application/javascript
            application/x-javascript
            application/json;
    }

Changes to docker-compose.yaml to map port and make it accessible.

            - 32000
        ports:
            - "80:80"
            - "443:443"
            - "32000:32000"

After these changes you can connect to the console using the X-Hasura-Access-Key when prompt. There you can generate your queries that you are going to use and mess around with the table definitions.