Table of Contents
How To Use GraphiQL to Understand the Sonar API
Read Time: 5 mins
1. The New Sonar API
2. A Deeper Dive into the New Sonar API
3. Mutations in the Sonar API
4. Consuming the Sonar API
GraphiQL Builtin IDE overview
The GraphiQL interface 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.
Within this interface, you can also view the documentation for each graphql call to see what format is required and their relationships.
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.
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
}
}Mutations (Create/Update/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 let's 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 it's an array since this takes an array of enums.
Updating a Role
Now that we have created this new role. Let's 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.
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
}
}
Let's go ahead and submit and get the results.
Now you've successfully deleted the role.
