Getting Started with the REST API

The Axonius platform is an API first platform. This means that there is no server side pages being generated. Everything that the UI can do, it is doing via our REST API.  That makes using our REST API a very flexible method of working with the Axonius server.


JSON:API

JSON:API is a specification created to maintain a standard structure in the data that is both sent and received from a REST API. We use this to maintain quality and uniformity in our API calls. For more information the specification can be found here: (JSON:API)[https://jsonapi.org/format/].


OpenAPI

OpenAPI is a specification designed to to help document a REST API in a manner that can be interpreted by both humans and computers alike. We use this to document our API calls and provide an API endpoint that can be used to pull this documentation directly from the server.

It is recommended to pull this directly from your own Axonius server as there may be changes between versions.


API Authentication

We use an API key / secret system as a means to authenticate to the REST API.

Getting the API Key and Secret

Retrieving your API Key and Secret can be done a couple of ways depending on what account type you are using (eg. user account vs service account). We have detailed documentation on this available here: https://docs.axonius.com/docs/api.

When you are making requests to our REST API, two headers need to be added to identify your API key and secret. For the key, the correct header is api-key and for secret it is api-secret.

 

Using the OpenAPI Specification File

Pulling the Specification File

There are two main ways to pull the OpenAPI specification YAML file. The first is to use the Axonius python client CLI tool called axonshell. You can learn how to get started with axonshell here: https://support.axonius.com/hc/en-us/community/posts/4786941189143-Getting-Started-with-Axonshell.

To pull the specification file you can simple do:

axonshell openapi get-spec

This will download the file to the current working directory for you to work with.

The other way to pull the specification file is via anything that can work with the REST API directly. In this example we will use curl:

curl -k -H "api-key: <yourapikey>" -H "api-secret: <yourapisecret>" https://<youraxoniusserver>/api/open_api_yaml

 

Viewing with Swagger Editor

Because the OpenAPI specification was created by Swagger, it can be imported into their editor. This will produced a nice graphical view of all documented API endpoints. Simple copy the contents from the specification file and paste it into the left side of the Swagger Editor. The editor can be found here: https://editor.swagger.io/.

Importing into Postman

The OpenAPI specification is supported by Postman. Therefore, the file downloaded from your Axonius server can be imported directly into Postman as a collection. To do so perform the following steps:

1) Click import.

2) Select the specification file acquired earlier.

3) Click the orange import button.

4) Collection has been imported.

 

Putting it all Together

Lets go ahead and test that everything is working like it should. For this example we will be making a REST call to return the number of devices our system has found.

To keep thing simple we will use a simple curl command for demonstration purposes, but anything that can send web requests will work so long as it is able to set headers in the request.

If we take a look at our OpenAPI specification file in Swagger Editor we will see the following:

This tells us that we need to use a "GET" HTTP method and make the request to "/api/devices/count". Because this is a GET request, there is no body that needs to be sent. There also are no parameters as part of the URL that we need to include so we are find there as well.

To make this request using CURL, we would do the following:

(the api-key and api-secreat as well as server URL would need be set for your environment)

❯ curl -k -H "api-key: r0zQTjk2P-POLb_PB8A7_bjLlWrecZOjam5OHwdfhI0" -H "api-secret: 14uGiLuxsjcYJ6ctlyrkkzdSkiOmwcUpFG-LI3tyC9I" https://10.20.0.21/api/devices/count

If everything went well you should see output similar to the following:

{"data":{"attributes":{"value":4063},"type":"int_value_schema"}}

And if we pretty that up a bit:

{
    "data":
    {
        "attributes":
        {
            "value": 4063
        },
        "type": "int_value_schema"
    }
}

You can see that we have a well formatted JSON:API object that is of type "int_value_schema". This object contains a single data attribute called "value" and its value is 4063. This is the exact number of devices on this instance.

5

Comments

0 comments

Please sign in to leave a comment.

Didn't find what you were looking for?

New post