---
id: rest-api
title: REST API
sidebar_label: REST API
keywords: [configuration, api, rest]
description: Configure the REST API
---

import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
import PageLink from "../src/components/PageLink";

The hyperglass API is based on the powerful [FastAPI](https://fastapi.tiangolo.com/) framework, which includes automatic API documentation using the [OpenAPI](https://www.openapis.org/) specification. If you plan to provide your users with API access to your hyperglass instance, it is highly recommended to leave this enabled.

FastAPI provides built in support for both [Swagger UI](https://swagger.io/tools/swagger-ui/) and [Redoc](https://redocly.github.io/redoc/), which are open source projects that create a pretty web UI from an OpenAPI specification.

## Settings

| Parameter     |  Type   | Default                            | Description                                                                                                                    |
| :------------ | :-----: | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `enable`      | Boolean | `true`                             | Enable or disable the API documentation.                                                                                       |
| `title`       | String  | `'{site_title} API Documentation'` | API documentation title. `{site_title}` will be replaced with the [`site_title`](parameters.mdx#global-settings) parameter.    |
| `description` | String  |                                    | API documentation description appearing below the title.                                                                       |
| `base_url`    | String  | `'https://lg.example.net'`         | The base URL for your hyperglass site. Used by OpenAPI for dynamically creating hyperlinks.                                    |
| `mode`        | String  | `'redoc'`                          | OpenAPI UI library to use for the hyperglass API docs. <MiniNote>Must be <Code>redoc</Code> or <Code>swagger</Code></MiniNote> |
| `uri`         | String  | `'/api/docs'`                      | HTTP URI/path where API documentation can be accessed.                                                                         |
| `openapi_uri` | String  | `'/openapi.json'`                  | Path to the automatically generated `openapi.json` file.                                                                       |
| `queries`     |         |                                    | `/queries` endpoint settings <PageLink to="#queries">➡️</PageLink>                                                             |
| `query`       |         |                                    | `/query` endpoint settings <PageLink to="#query">➡️</PageLink>                                                                 |
| `devices`     |         |                                    | `/devices` endpoint settings <PageLink to="#devices">➡️</PageLink>                                                             |

### `queries`

| Parameter     |  Type  | Default                            | Description                                                  |
| :------------ | :----: | :--------------------------------- | :----------------------------------------------------------- |
| `title`       | String | `'Supported Queries'`              | Displayed as the header text above the API endpoint section. |
| `description` | String | `'List of supported query types.'` | Displayed inside each API endpoint section.                  |
| `summary`     | String | `'Query Types'`                    | Displayed beside the API endpoint URI.                       |

### `query`

| Parameter     |  Type  | Default                                    | Description                                                  |
| :------------ | :----: | :----------------------------------------- | :----------------------------------------------------------- |
| `title`       | String | `'Submit Query'`                           | Displayed as the header text above the API endpoint section. |
| `description` | String | `'Request a query response per-location.'` | Displayed inside each API endpoint section.                  |
| `summary`     | String | `'Query the Looking Glass'`                | Displayed beside the API endpoint URI.                       |

### `devices`

| Parameter     |  Type  | Default                                                                                         | Description                                                  |
| :------------ | :----: | :---------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |
| `title`       | String | `'Devices'`                                                                                     | Displayed as the header text above the API endpoint section. |
| `description` | String | `'List of all devices/locations with associated identifiers, display names, networks, & VRFs.'` | Displayed inside each API endpoint section.                  |
| `summary`     | String | `'Devices List'`                                                                                | Displayed beside the API endpoint URI.                       |

## Example

```yaml title="hyperglass.yaml"
docs:
  base_url: https://lg.example.net
  description: ""
  devices:
    description:
      List of all devices/locations with associated identifiers, display
      names, networks, & VRFs.
    summary: Devices List
    title: Devices
  enable: true
  mode: redoc
  openapi_uri: /openapi.json
  queries:
    description: List of supported query types.
    summary: Query Types
    title: Supported Queries
  query:
    description: Request a query response per-location.
    summary: Query the Looking Glass
    title: Submit Query
  title: "{site_title} API Documentation"
  uri: /api/docs
```

:::note From the developer
I'm partial to Redoc, partially because I find it to be more aesthetically pleasing, and partially because it's written in [ReactJS](https://reactjs.org/), just like the hyperglass UI. At some point, I plan to migrate away from the built-in Redoc page and integrate Redoc directly with hyperglass.
:::