Skip to main content

Discover inventories

Before it queries entities, a consumer can list the inventories, read an inventory's fields and location hierarchy, and list the source connections.

List inventories​

curl -s localhost:8080/v1/inventories
{
  "inventories": [
    {
      "id": "devices",
      "description": "Network devices from Infrahub and NetBox",
      "entity_kind": "device",
      "status": "ready",
      "completeness": { "complete": true, "causes": [] }
    }
  ]
}

status is ready, or rebuilding while Census applies a configuration change. While an inventory is rebuilding, completeness is null and its entity, lookup, location and diagnostics routes answer 503 inventory-rebuilding. completeness is for the default view.

Read an inventory's definition​

curl -s localhost:8080/v1/inventories/devices

The response is the inventory's configuration: its fields with their types, vocabularies, defaults and priorities, the inventory's priority, the freshness budgets, the location hierarchy, and each contribution's connection id, object types, HFID path, attribute paths, value mappings, defaults, location paths and refresh interval. Durations are given in seconds, in keys that end with _secs, for example freshness_default_secs. Connections appear by id only, without endpoint or credentials.

Use it to learn which fields a consumer can filter and sort on, their types, and the values a field with a vocabulary can take. This route answers during a rebuild.

Read the location hierarchy​

curl -s localhost:8080/v1/inventories/devices/locations
{
  "levels": ["region", "site", "rack"],
  "locations": [
    {
      "path": "eu", "level": "region", "name": "eu",
      "children": [
        {
          "path": "eu/par1", "level": "site", "name": "par1",
          "children": [
            { "path": "eu/par1/r01", "level": "rack", "name": "r01", "children": [] }
          ]
        }
      ]
    }
  ]
}

A location's path is the value to pass in location= and the value of an entity's location.

List source connections​

curl -s localhost:8080/v1/connections
{
  "connections": [
    {
      "id": "infrahub-prod",
      "type": "infrahub",
      "branching": true,
      "used_by": [ { "inventory": "devices", "contribution": "infrahub" } ]
    },
    {
      "id": "netbox-prod",
      "type": "netbox",
      "branching": false,
      "used_by": [ { "inventory": "devices", "contribution": "netbox" } ]
    }
  ]
}

branching tells whether the source can supply branch data.