Table of Contents

How To Use GraphiQL to Understand the Sonar API

Chris Trower Updated by Chris Trower

GraphiQL Builtin IDE overview

The GraphiQL interfaces allows you to run mutations and queries within your web browser without the need to write any code. This allows you to find and even edit collections of data directly from the web interface. For a basic understanding of GraphQL language and syntax, please check out https://graphql.org/learn/. To access the GraphiQL interface within your sonar instance type "/graphiql" at the end of your instance domain.

example: https://example.sonar.software/graphiql

Within this interface you can also view the documentation for each graphql call to see what format is required, and their relationships.

You can also access the Sonar GraphQL docs at https://api.sonar.software

GraphQL Usage Examples

Query Request - Querying Inventory IP Assignments

In Sonar, IP Assignments can be attached to Inventory items both directly, or through Inventory Item Field Data, such as the IMSI or the MAC Address. In this scenario, we'll be running through the commands to query your instance's inventory and gathering the IP Assignment information.

To start writing a query, click the left hand side of the interface. You can either start writing directly on the next line or clear the text and start from the top.

Using the following Query:

query inventory {
inventory_items {
entities {
ip_assignments {
entities {
subnet
}
}
inventory_model_field_data {
entities {
ip_assignments {
entities {
id
subnet
}
}
}
}
}
}
}

When you run this you'll receive the following reply, listing all inventory items and their assigned IP Addresses on your instance:

Now, with the way we ran this you don't see the ID or inventory information, so let's go ahead and add some additional fields to pull.

query inventory{
inventory_items{
entities{
id
inventory_model {
name
}
ip_assignments{
entities{
id
subnet
}
}
inventory_model_field_data{
entities{
id
value
ip_assignments{
entities{
id
subnet
}
}
}
}
}
}
}

Pagination

In graphiql, results from a query will default to 100 results. If you require more results you can accomplish this through pagination. To apply pagination, we must first specify this at the start of the query, as well as which object we want to return that many results. Through pagination, up to 10000 records per page can be displayed. You can also select which page you would like to do for datasets that exceed 10000 lines. Below is an example of how to paginate requests:

Query:

query ($paginator: Paginator) {
addresses(paginator: $paginator) {
entities {
id
line1
}
}
}

Query Variables:

{
"paginator": {
"page": 1,
"records_per_page": 10000
}
}
It is generally best practice to use a query variable so that you can change the number of records displayed or which page to display on the fly.

Mutations (Create/Updated/Delete Data) - Modifying your data

GraphQL can also be used to modify values in your instance, such as in the case of inventory in the previous example. GraphQL can be used to create, update, or delete an item. A great example of mutation usage is Role Mutation. In the following example, we'll be looking at adding, updating, and deleting a role.

Create a Role mutation

You can view what is required for a specific mutation by reviewing the Documentation Hub and clicking on "Docs" in the top left corner of the results pane. If you start to type createrole in the search bar, you'll begin to see the mutations that match that. You then can click on the results and see which fields are required and which are optional.

You'll want to click on the "CreateRoleMutationInput" result. This will show you what fields you can add within the GraphiQL Request Interface.

Now if you see the ! mark that means it's required. You can then click on [Permission!] for example and this will show you all of the permissions you can apply to this role.

Now lets apply the READ_ALL_LOGS and READ_CALL_LOG to this new role using the following command:

mutation createRole {
createRole(input: {
name: "Read logs and call",
applied_permissions: [
READ_ALL_LOGS
READ_CALL_LOG
]
}){
id
name
applied_permissions
}
}

When you click submit on this mutation, you'll get returned the id, name, and applied_permissions. Keep in mind under the second {} brackets is what you want returned. You could simply just return applied_permissions. Also within the applied_permissions its an array since this takes an array of enums.

Updating a Role

Now that we have created this new role. Lets say we want to remove the READ_CALL_LOG from this role. You'll need to know the ID which we have on this return. So you can pull up the documentation for UpdateRoleMutationInput and see what can be applied. In this case it's a similar format:

mutation updateRole {
updateRole (id: 9, input: {
name: "Read logs and calls"
applied_permissions: [
READ_ALL_LOGS
]
}){
id
name
applied_permissions
}
}

Now once you apply this it will update the permissions and you'll receive the following;

Now this role only has READ_ALL_LOGS.

The ID section of the code will be the ID of the role you'd like to change. In our example, it's 9, but that might change with your instance.
Role Deletion Example

Now let's say we need to delete this role. We created it in error. If you look in the documentation the deleteRole only requires an ID which we have from above ID 9.

mutation deleteRole {
deleteRole(id: 9){
message
success
}
}

Lets go ahead and submit and get the results.

Now you've successfully deleted the role.

Additional Resources

https://graphql.org/learn/

https://www.howtographql.com/

How did we do?

How Your Data is Backed Up

Frequently Used Terms

Contact