GraphQL

Humio has chosen GraphQL for our main API because it offers significantly more flexibility for API clients. GraphQL allows you to precisely specify the data you require, which allows you to call a single endpoint to get everything you need. This makes creating integrations and clients for Humio much easier.

Updates and changes to the GraphQL API are backwards compatible with previous versions; changes to the API should not cause existing scripts using the API to fail after an upgrade.

API Explorer

Humio has a built-in, interactive API explorer bundled with each installation. You can find it under:

You don’t need any special tools to use GraphQL. GraphQL is based on HTTP, and all you need is curl to send requests; responses are returned as JSON.

Resources for Learning GraphQL

Examples

These examples are geared toward self-hosted setups and assume they’re being executed from a Humio server. You can also run them against the public Humio hostname using an actual user API token (which is obtained from the Your Account area from the menu on the right in the header). This is being done for simplicity’s sake and the fact that it will work on any installation if executed from the server running Humio.

List Users:

shell
curl -v -XPOST -H "Content-Type: application/json" \
  -H "Authorization: bearer $(cat /data/humio-data/local-admin-token.txt)" \
  http://127.0.0.1:8080/graphql \
  -d '{ "query": "{ accounts { username } }" }'

Add User:

shell
curl -v -XPOST -H "Content-Type: application/json" \
  -H "Authorization: bearer $(cat /data/humio-data/local-admin-token.txt)" \
  http://127.0.0.1:8080/graphql \
  -d '{ "query": "mutation { addUser(input: { username: \"user@example.com\" }) { user { id } } }" }'

Remove User:

shell
curl -v -XPOST -H "Content-Type: application/json" \
  -H "Authorization: bearer $(cat /data/humio-data/local-admin-token.txt)" \
  http://127.0.0.1:8080/graphql \
  -d '{ "query": "mutation { removeUser(input: { username: \"user@example.com\" }) { user { id } } }" }'

Both GraphQL and REST

Some resources in Humio must be accessed with REST. This is both for historical reasons and that we feel that REST is better suited for our Querying API. Also, HTTP streaming is more appropriate for our streaming results, though we may add support for GraphQL Subscriptions in the future.