API Usage¶

Sicura Console provides a robust backend with a thorough API that allows for easy access and manipulation of any data used in the Console. This page gives an overview of how to access and make use of the available APIs.

Health Check and Readiness API¶

To allow the Console to be used in a Kubernetes or scaled environment, we provide health check endpoints for quick checking of basic Console functionality.

`GET /health`¶

Status: 200
Body: 'SicuraConsole OK'

`GET /readiness`¶

Returns status 200 when the Console is ready and 503 when it is not:

{
  "all_ready": "ok",
  "checks": {
    "core_ready": "ok",
    "db_ready": "ok",
    "system_session_ready": "ok",
    "workers": {
      "collector": "ok"
    }
  }
}

OpenAPI Documentation¶

In order to build any tooling that may interface with the Console, you'll need to use the provided REST API. All API definitions can be accessed from the API reference, which is easily found by clicking the user menu at the bottom-left corner of the navigation sidebar and selecting the API Reference menu item.

User menu showing the API Reference menu item

After clicking, the OpenAPI documentation will appear with specific access based on the user logged into the Console.

The OpenAPI documentation page listing the API collections

Provided is a list of every API Collection that is defined in our REST framework. Clicking one will show you all of the operations that can be made on that collection. For this example we'll show the most complex API: infrastructure/v1/nodes.

The operations available on the nodes collection

Start by selecting the first GET option. This is for the entire collection, as opposed to the later GET which is specifically used only if you know the ID of a particular individual object you want to grab.

The collection GET operation, showing the attributes and filter parameters

The above screen has two sections to focus on:

Attributes¶

This is a list of all attributes associated with a particular object or collection (node or nodes in this example). You can limit the data returned by selecting only the attributes you want.

Note: Most APIs have a set of default attributes that will return regardless of the user's selection in the attribute field.

Filter¶

When querying a large collection, the filter option can be useful as it allows you to narrow down the returned list of objects in that collection. All attributes and their specified datatype are listed for you in the filter initially. Delete any attributes you do not want to filter by and change the datatype to the data you're looking for on any attributes you do want to filter by. For example, to return only RHEL 9 nodes you would modify the filter to be "platform": "cpe:/o:redhat:enterprise_linux:9" and delete everything else from the filter. An empty response [] will be returned if there are no matches for your filter.

Once selections have been made, click the Try button to get the response. An example curl command with your selections is provided, for easy copy-paste into your tool.