Skip to main content

REST API

The hyperglass API is based on the powerful FastAPI framework, which includes automatic API documentation using the OpenAPI 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 and Redoc, which are open source projects that create a pretty web UI from an OpenAPI specification.

Settings#

ParameterTypeDefaultDescription
enableBooleantrueEnable or disable the API documentation.
titleString'{site_title} API Documentation'API documentation title. {site_title} will be replaced with the site_title parameter.
descriptionStringAPI documentation description appearing below the title.
base_urlString'https://lg.example.net'The base URL for your hyperglass site. Used by OpenAPI for dynamically creating hyperlinks.
modeString'redoc'OpenAPI UI library to use for the hyperglass API docs. Must be redoc or swagger
uriString'/api/docs'HTTP URI/path where API documentation can be accessed.
openapi_uriString'/openapi.json'Path to the automatically generated openapi.json file.
queries/queries endpoint settings ➡️
query/query endpoint settings ➡️
devices/devices endpoint settings ➡️

queries#

ParameterTypeDefaultDescription
titleString'Supported Queries'Displayed as the header text above the API endpoint section.
descriptionString'List of supported query types.'Displayed inside each API endpoint section.
summaryString'Query Types'Displayed beside the API endpoint URI.

query#

ParameterTypeDefaultDescription
titleString'Submit Query'Displayed as the header text above the API endpoint section.
descriptionString'Request a query response per-location.'Displayed inside each API endpoint section.
summaryString'Query the Looking Glass'Displayed beside the API endpoint URI.

devices#

ParameterTypeDefaultDescription
titleString'Devices'Displayed as the header text above the API endpoint section.
descriptionString'List of all devices/locations with associated identifiers, display names, networks, & VRFs.'Displayed inside each API endpoint section.
summaryString'Devices List'Displayed beside the API endpoint URI.

Example#

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
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, 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.