JDisc Discovery GraphQL API

Did you know that JDisc Discovery has a API for programmatic access of all the discovery data and functionality? In this article we want to introduce this programming interface and have a deeper look at the how to use it with various programming languages.

Most often application have today RESTful APIs, that follow the REST resource-oriented paradigm using the REST operations GET, PUT, POST, DELETE with URLs, query string and JSON payloads. While this if perfectly fine for many applications, for a solution like JDisc Discovery with its very rich object model the REST style would mean hundreds of resources and payload schemas and complex query parameters with hundreds of pages of API documentation in order to use it. The complexity would be overwhelming for developers.

Luckily there is a modern alternative API style and this is GraphQL (https://graphql.org/) from the GraphQL Foundation. With a GraphQL API an application has a single endpoint and the API queries are realized as JSON payload requests. By the way, JDisc Discovery only offers a secure HTTPS endpoint under https://<server>/graphql.

https://youtu.be/ePqWFkfJ9e4

Classic Data Export

Before we delve into the new GraphQL API, let’s look how we can get discovery data out of the server and database up until now. In the UI every view that his available has iconic action buttons to export the data shown in the view as Excel or comma-separated values report:

data export

Also the second marked icon shows you the SQL query that is underlying the view. This query can be copied, modified and used in SQL development tools or in scripts to access the corresponding data programatically.

SQL Query

While the JDisc database schema is pretty stable, there is no guarantee and the downside of using such a direct database access is obvious. New versions might break the code, architecturally it is a low-level access to data and from the security standpoint this should be avoided, even if using a read-only database user might help to mitigate unintended data modification.

GraphQL API

The GraphQL high-level API is the new official way to access data from discovery programatically. To learn more about GraphQL see https://graphql.org/learn. Why is GraphQL the better fit for JDisc Discovery? Because it has a fix and consise object model in contrast to a CMDB that has a very generic and flexible information model. This is intentionally so, as we discussed in the the corresponding article on discovery automation for CMDB. GraphQL is not very well suited for such flexible, potentially even recursive information models but for Discovery APIs it is perfect.

Having one endpoint and a query language that represents directly the object model of the discovery service makes it easy to use. The second is that JDisc Discovery comes with a getting started guide built into the UI right ouf the box.

integration api

Plus it has a GraphQL development environment (IDE) build right into the Web UI as well, so that developers can try queries without having to install additional tooling first.

GraphQL Schema

The following is the GraphQL schema for JDisc Discovery:

Discovery API GraphQL Schema
Discovery API GraphQL Schema

But luckily you do not have to learn this. First the schema file can be downloaded in the GraphQL schema language from the JDisc web UI.

Integrated GraphQL IDE

Furthermore in the JDisc web UI integrated development and test environment for the GraphQL API helps developers test their queries and mutations. As part of this IDE there is a documentation explorer that allows to click through the API schema.

Integrated GraphQL IDE

This helps a lot especially as the UI does the authentication for you and tested queries can then be copied to API scripts and one is sure that they work.

API Use Cases

GraphQL support is present for many programming languages, as one can see on the GraphQL website:

language support

All API sample projects can be found on the JDisc Github organization https://github.com/jdisc. As programming languages we choose, simply based on the author’s knowledge:

  • Groovy
  • Python
  • Golang

For each sample we choose a use case that is not totally useless but not a productive tool either:

  • Groovy: query all Cisco switches and get the setting on the start configuration. Report all devices those start configuration has not been saved
  • Python: Get installed application of all devices of a network and create a software bill of material (SBOM) in CycloneDX format from it.
  • Golang: A server that looks for a lockfile, written by a backup script. Then triggers a discovery job when the lockfile is not present.

For some use cases we will also create a separate blog article later, such as SBOM generation. For these sample we need to make a decision on the GraphQL library to choose. This has been done based on a quick investigation and the fact that we only need a client library.

Testing with Postman

You can find a sample Postman collection at https://github.com/jdisc/discovery-api-postman in the JDisc Github organisation. Of course the single endpoint http://<server>/graphql is protected authentication, so we need to authenticate first before we can send a query or mutation request.

Postman does support GraphQL directly, so we can make use of variables in the authentication mutation:

mutation($user: String, $password: String) {
    authentication {
        login(login: $user, password: $password) {
            status
            accessToken
            refreshToken
        }
    }
}

Plus we pass variables separately

{
    "user": "{{discovery-user}}",
    "password": "{{discovery-pass}}"
}

This should return you a status code of 200 and a payload in the form of (tokens shortened):

{
    "data": {
        "authentication": {
            "login": {
                "status": "SUCCESS",
                "accessToken": "eyJ0...xwcBy_BS-Q",
                "refreshToken": "eyJ0...20IZw"
            }
        }
    }
}

In the code of your client you can now grab the accessToken from this response and set the Authorization HTTP header using this Bearer token in all following requests, just like you would be using JWT and OAuth2/OIDC.

Authorization: Bearer eyJ0...xwcBy_BS-Q

How this is done of course depends on your programming language and GraphQL library of choice.

postman

Postman can use a GraphQL schema when you create an API and upload the schema, that you downloaded from the JDisc IDE as described before.

When you check out the Postman collection, you will see there is a little trick in the authentication request with a JS test

var res = pm.response.json();
pm.environment.set('discovery-api-token', 
res.data.authentication.login.accessToken);

which stores the access token in the environment for the next query requests to pick it up automatically. So in the sample request we just set the authentication to “Bearer token” and refer to the environment variable “{{discovery-api-token}}

Summary

The sample projects on Github are still private repositories and will be published when working well. If you have great ideas for API clients for the new discovery API or want to even contribute code on Github, such as a cool client that would be useful to others, let us know!

Also check out the previous discovery API announcement article on the blog.

Leave A Comment


The reCAPTCHA verification period has expired. Please reload the page.