Network Query Engine (NQE) by Forward Networks provides information about the network as JSON data in a fully-parsed form. The information is normalized and presented uniformly across devices from different vendors. The exported data structures are standards-aligned with OpenConfig (details below), and all data is available through a GraphQL API as well as custom verification checks directly in the Forward Enterprise browser-based interface (In-App NQE Checks).
This repository helps you get started with the NQE GraphQL interface. The main NQE repository containing general/common info/background on NQE is here while the repository containing in-app NQE Checks information and a set of examples is here.
In particular, this repository walks you through the process of interactively crafting queries against a Forward Networks instance and explains the request and response structure of the API. This repository also includes a simple Python client library that you can use to write Python scripts that query and consume NQE data. This README describes how to install that library and provides example scripts that use this client library in interesting ways. Finally, it provides all the information needed to configure and use Postman as GraphQL client.
You can use any GraphQL client to consume NQE data.
To get started you can use one of these options:
The quickest way to get started is to try out sample queries against a demo network on Forward App. Note that if you do not already have an account there, you can request an account here.
Browse to the Network Query Explorer in app. Use the network and snapshot selectors in the toolbar to select the demo network and its snapshot. Now try out the following simple query, by dropping the following query into the left hand-side pane and running the play button:
{
devices {
name
}
}
You should see output like this in the right hand-side pane, containing all the device names in the demo network:
You can try out other queries. The editor provides assistance via auto-complete and inline help, which you can access by pressing control+shift keys. In addition, you can explore the full schema, including detailed formal and informal documentation, by opening the "Docs" pane in the top-right-hand side toolbar.
Note that you can try out these queries against your own network snapshot by choosing the appropriate network and snapshot on the query window.
This repository includes a simple client library that can be used to run queries. The library is verified to work on Python versions 2.6, 2.7, 3.4, 3.5 and 3.6.
Install the library like this:
pip install -r requirements.txt .
Root permissions may be required to run the above command.
Now you can run the examples in the examples/ directory. For example, in the examples directory, run:
python mismatched_interfaces.py https://fwd.app <yourUsername> <yourPassword> <yourSnapshotId>
You should see the following output:
Postman is a popular HTTP API testing and development environment. Mostly used for REST APIs, now Postman supports GraphQL as well.
Unfortunately, it doesn't support GraphQL Introspection, a key feature that allows to populate the schema inspector, provides autocomplete and enables to easily build schema documentation.
The GraphQL schema can be imported manually instead, providing autocomplete but no documentation. GraphQL Schema Definition Language (SDL) is the only format supported.
The schema in SDL format can be exported from the Forward Platform using tools like get-graphql-schema or by running this Introspection query in the Network Query Explorer and converting the JSON output to the SDL format using tools like graphql-introspection-json-to-sdl:
The picture below shows a simple query to get device platform details:
Select JSON format from the drop down menu (step 3 in the picture above) for a prettier data visualization.
The repository provides the following example queries and scripts:
- Show All Device Names. This is a simple example to list all devices in a network.
- Show Unique Platforms. This script shows the unique Vendor, model, and OS combinations in a network.
- Show MAC Table. This script prints the MAC table of all devices in a network snapshot.
- Show ARP Table. This script prints the IPv4 ARP table of all devices in a network snapshot.
- Find interfaces with clashing configured and operational status. Interfaces can be configured up, but can be operationally down for a variety of reasons. This script finds cases where the states differ, so that an operator can do further investigation.
- Find IP addresses that are assigned to more than one interface within a VRF. Assigning a single IP address to multiple interfaces in a network can often lead to problems. This script queries Forward Networks NQE and finds all violations of this problem, showing the interfaces on which each duplicate IP address is assigned.
The API is available via HTTP POST to the following URL
https://<ForwardInstance>/api/snapshots/<SnapshotId>/graphql
The body of the POST should follow the standard GraphQL request JSON structure. Specifically, it should include a query field to hold the query string, and an optional variables field to pass variables used by the query (see here for background on GraphQL variables):
{ "query": "<your query>", "variables": [{"var1", "value1"}, ..., {"varn", "valuen"}]}
The API is authenticated via basic auth.
For example, you can issue the query shown previously via curl against https://fwd.app as follows:
curl --user myusername:mypassword https://fwd.app/api/snapshots/100/graphql -X POST -H "Content-Type: application/json" -d '{"query": "{ devices { name } }"}'
We welcome contributions! Please submit and share scripts, queries, and examples. Bug fixes, doc improvements and so on are also welcome. To contribute, fork the repository, push your work to a branch in that repository and then submit a pull request. Specifically, do:
- Fork this repository
- Clone your forked repository
- In your forked repository, create your feature branch (
git checkout -b my-feature) - Push to the new branch of your forked repository: (
git push origin my-feature) - Create new Pull Request
@AndreasVoellmy or use the project GitHub issues.