diff --git a/docs/graphql-api/overview.md b/docs/graphql-api/overview.md new file mode 100644 index 000000000..b202d77af --- /dev/null +++ b/docs/graphql-api/overview.md @@ -0,0 +1,68 @@ +# GraphQL API Overview + +NetBox provides a read-only [GraphQL](https://graphql.org/) API to complement its REST API. This API is powered by the [Graphene](https://graphene-python.org/) library and [Graphene-Django](https://docs.graphene-python.org/projects/django/en/latest/). + +## Queries + +GraphQL enables the client to specify an arbitrary nested list of fields to include in the response. All queries are made to the root `/graphql` API endpoint. For example, to return the circuit ID and provider name of each circuit with an active status, you can issue a request such as the following: + +``` +curl -H "Authorization: Token $TOKEN" \ +-H "Content-Type: application/json" \ +-H "Accept: application/json" \ +http://netbox/graphql/ \ +--data '{"query": "query {circuits(status:\"active\" {cid provider {name}}}"}' +``` + +The response will include the requested data formatted as JSON: + +```json +{ + "data": { + "circuits": [ + { + "cid": "1002840283", + "provider": { + "name": "CenturyLink" + } + }, + { + "cid": "1002840457", + "provider": { + "name": "CenturyLink" + } + } + ] + } +} +``` + +!!! note + It's recommended to pass the return data through a JSON parser such as `jq` for better readability. + +NetBox provides both a singular and plural query field for each object type: + +* `object`: Returns a single object. Must specify the object's unique ID as `(id: 123)`. +* `objects`: Returns a list of objects, optionally filtered by given parameters. + +For more detail on constructing GraphQL queries, see the [Graphene documentation](https://docs.graphene-python.org/en/latest/). + +## Filtering + +The GraphQL API employs the same filtering logic as the UI and REST API. Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only sites within the North Carolina region with a status of active: + +``` +{"query": "query {sites(region:\"north-carolina\", status:\"active\") {name}}"} +``` + +## Authentication + +NetBox's GraphQL API uses the same API authentication tokens as its REST API. Authentication tokens are included with requests by attaching an `Authorization` HTTP header in the following form: + +``` +Authorization: Token $TOKEN +``` + +## Disabling the GraphQL API + +If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/optional-settings.md#graphql_enabled) configuration parameter to False and restarting NetBox. diff --git a/mkdocs.yml b/mkdocs.yml index 89b72d433..031fab634 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,6 +87,8 @@ nav: - Overview: 'rest-api/overview.md' - Filtering: 'rest-api/filtering.md' - Authentication: 'rest-api/authentication.md' + - GraphQL API: + - Overview: 'graphql-api/overview.md' - Development: - Introduction: 'development/index.md' - Getting Started: 'development/getting-started.md'