GraphQL¶

Nautobot supports a Read-Only GraphQL interface that can be used to query most information present in the database. The GraphQL interface is available at the endpoint graphql/ for a human to explore and GraphQL can be queried as an API via the endpoint api/graphql/. Currently the support for GraphQL is limited to query, other operation type like mutations and subscriptions are not supported. Additionally, GraphQL variables are supported.

The GraphQL implementation is leveraging the graphene-django library and supports the standard GraphQL language.

How to use the GraphQL interface¶

The GraphQL interface can be used to query multiple tables at once in a single request. In GraphQL, only the information requested will be returned which can be contrasted to REST APIs. In the example below, this query will return the name of all interfaces attached to the device nyc-sw01 along with all ip_addresses attached to those interfaces.

query {
  devices(name: "nyc-sw01") {
    name
    interfaces {
      name
      ip_addresses {
        address
      }
    }
  }
}

Result

{
  "data": {
    "devices": [
      {
        "name": "nyc-sw01",
        "interfaces": [
          {
            "name": "xe-0/0/0",
            "ip_addresses": [
              {
                "address": "10.52.0.1/30"
              }
            ]
          },
          {
            "name": "xe-0/0/1",
            "ip_addresses": []
          }
        ]
      }
    ]
  }
}

It is possible to explore the Graph and create some queries in a human friendly UI at the endpoint graphql/. This interface (called graphqli) provides a great playground to build new queries as it provides full autocompletion and type validation.

Querying the GraphQL interface over the rest API¶

It is possible to query the GraphQL interface via the rest API as well, the endpoint is available at api/graphql and supports the same Token based authentication as all other Nautobot APIs.

A GraphQL Query must be encapsulated in a JSON payload with the query key and sent with a POST request. Optionally it is possible to provide a list of variables in the same payload as presented below.

{
  "query": "query ($id: Int!) { device(id: $id) { name }}",
  "variables": { "id": 3}
}

Working with Custom Fields¶

GraphQL custom fields data data is provided in two formats, a "greedy" and a "prefixed" format. The greedy format provides all custom field data associated with this record under a single "custom_field_data" key. This is helpful in situations where custom fields are likely to be added at a later date, the data will simply be added to the same root key and immediately accessible without the need to adjust the query.

query {
  sites {
    name
    custom_field_data
  }
}

Result

{
  "data": {
    "sites": [
      {
        "name": "nyc-site-01",
        "custom_field_data": {
          "site_type": "large"
        }
      },
      {
        "name": "nyc-site-02",
        "custom_field_data": {
          "site_type": "small"
        }
      }
    ]
  }
}

Additionally, by default, all custom fields in GraphQL will be prefixed with cf. A custom field name site_type will appear in GraphQL as cf_site_type as an example. The prefix can be changed or remove the prefix by setting the value of GRAPHQL_CUSTOM_FIELD_PREFIX.

query {
  sites {
    name
    cf_site_type
  }
}

Result

{
  "data": {
    "sites": [
      {
        "name": "nyc-site-01",
        "cf_site_type": "large"
      },
      {
        "name": "nyc-site-02",
        "cf_site_type": "small"
      }
    ]
  }
}

Saved Queries¶

Queries can now be stored inside of Nautobot, allowing the user to easily rerun previously defined queries.

Inside of Extensibility -> Data Management -> GraphQL Queries, there are views to create and manage GraphQL queries.

Saved queries can be executed from the detailed query view or via a REST API request. The queries can also be populated from the detailed query view into GraphiQL by using the "Open in GraphiQL" button. Additionally, in the GraphiQL UI, there is now a menu item, "Queries", which can be used to populate GraphiQL with any previously saved query.

To execute a stored query via the REST API, a POST request can be sent to /api/extras/graphql-queries/[slug]/run/. Any GraphQL variables required by the query can be passed in as JSON data within the request body.