The Validio platform is exposing a GraphQL API which is accessible by any GraphQL client.

📘

All queries, mutations, and types are documented in the GraphQL API Reference.

Authentication

To authenticate your requests to the GraphQL API, you need to pass the Authorization header. The header value should be of format <access-key>:<access-secret>. Refer to Create API key on how to create credentials.

👍

You can use environment variables to avoid storing credentials on disk. The variables to set are VALIDIO_ENDPOINT, VALIDIO_ACCESS_KEY and VALIDIO_SECRET_ACCESS_KEY.

Namespaces

Namespaces are used to separate between resources. This means that the resources you create in one namespace are only visible from that namespace. For example, you can use namespaces to:

• Separate Validators by team.
• Assign a unique namespace to resources you create using IaC, to prevent overwriting similar already existing resources.

👍

We recommend that you explicitly assign a unique namespace to every project.

📘

A project's namespace is displayed in the validio.json file in the project directory.

Response limit

When listing incidents there's a limit of 1000 items returned. If you need more than that you can use a smaller TimeRange window and implement pagination.

Here is an example on how to query the last month of incidents split in daily pages and writing out some information about the incident using our SDK:

from datetime import datetime, timedelta

import validio_sdk.validio_client as vc
from validio_sdk.graphql_client import TimeRangeInput, ValidatorIncidentsInput


async def paginate_incidents(validator_id: str):
    client = vc.ValidioAPIClient()

    now = datetime.now()
    start_time = now - timedelta(days=30)
    interval_size = timedelta(days=1)
    page = 0
    incidents = []

    while start_time < now:
        response = await client.get_validator_incidents(
            ValidatorIncidentsInput(
                validator_id=validator_id,
                time_range=TimeRangeInput(
                    start=start_time,
                    end=start_time + interval_size,
                ),
            )
        )

        for incident in response:
            incidents.append((page, incident))

        start_time = start_time + interval_size
        page += 1

    for page, incident in incidents:
        print(
            f"{incident.metric.start_time} on page {page} value was"
            f" {incident.metric.value} ({incident.metric.operator} than"
            f" {incident.metric.bound})"
        )

Which would result in something similar to this:

2023-09-01 12:31:49.916000+00:00 on page 0 value was 48.0 (LESS than 50.0)
2023-09-01 12:31:45.487000+00:00 on page 0 value was 45.0 (LESS than 50.0)
[...]
2023-09-28 12:39:59.592000+00:00 on page 9 value was 41.0 (LESS than 50.0)
2023-09-28 12:39:57.231000+00:00 on page 9 value was 48.0 (LESS than 50.0)

Semi-structured data

In this section we describe the syntax for accessing and navigating semi-structured data and other complex data structures, using our API, SDK, or CLI.

JSONPath expressions

Validio leverages JSONPath to handle semi-structured and other complex data types. Currently, Validio supports a subset of the JSONpath syntax.

This example shows nested data using JSON syntax:

{  
   "agency":"MI6",  
   "user":{  
      "_id":"64591485781fd0a9e07be6c7",  
      "name":"Valencia Walls"  
   },  
   "contact-info":{  
      "company":"CONCILITY",  
      "phone":"+1 (885) 535-3971",  
      "address":"176 Visitation Place, 7052"  
   },  
   "friends":[  
      {  
         "id":0,  
         "name":"Candy Diaz"  
      },  
      {  
         "id":1,  
         "name":"Sherry Burch"  
      }  
   ]  
}

Notation

You can use the dot . notation, bracket notation with single quotes ['...'] or double quotes ["..."], or a combination of both to form expressions. For example, the following expressions are equivalent:

user.name, user["name"], user['name'], ['user']['name'] and ['user'].name

The bracket notation is required when a field contains special characters, such as the hyphen -. For example ['contact-info'].company is a valid expression, but contact-info.company is not a valid expression.

Valid characters in the dot . notation are alphanumeric characters, such as letters and digits, and underscore _. Identifiers that contain other characters require bracket notation.

Unlike most JSONPath dialects, the expressions do not begin with the optional dollar sign $, since an expression always starts from the root field. For example, the column name of a warehouse table. This enables use of the same syntax in expressions for both nested and non-nested data validations.

For example, agency => "M16" works the same regardless if the enclosing record contains nested fields.

Arrays

Validio can perform validations on array fields and on objects nested within array fields.

The array subscript [] notation selects a specific element in an array. For example, the following expression selects the element with id 1 in the friends array field:

friends[1].name => "Sherry Burch"

The syntax supports functions on arrays with the parenthesis () at the end of an expression. For example, the following expressions are equivalent:

friends.length(), friends['length']() => 2

The invoked function is the array length function, which results in the number of elements in the array.

📘

Currently, the JSONPath syntax only supports the length function for arrays.