InfraGraph

- Configuration
  - postset_graph
  - postget_graph
  - postannotate_graph
- Actions
  - postquery_graph
- Capabilities
  - getget_version

API docs by Redocly

# InfraGraph (0.4.0)

Download OpenAPI specification:Download

URL: https://github.com/keysight/infragraph/issues License: MIT

### Overview

InfraGraph or `infrastructure graph` defines a model-driven, vendor-neutral, standard interface for capturing a system of systems suitable for use in co-designing AI/HPC solutions.

This model allows for defining physical infrastructure as a logical system of systems using graph like terminology. In addition to defining a logical graph, an unlimited number of different physical characteristics can be associated with logical endpoints.

### Graph Terminology

- an infrastructure `node (vertex)` is the fundamental unit or entity within an infrastructure graph; represented as a endpoint with the following syntax:
  - a combination of a device instance name and a 0 based index and a component name and a 0 based index such as `switch.0.asic.0` and `switch.0.port.0`
- an infrastructure `edge` is a combination of two `nodes (endpoints)` in a graph such as (`switch.0.asic.0`, `switch.0.port.0`)
- `path` is a sequence of edges that allows for traversal through the graph such as [`server.0.npu.0`, `server.0.nic.0`, `switch.0.port.0`, `switch.0.asic.0`]

### Contributions

Contributions to the API and models schema can be made in the following ways:

- open an issue in the models repository
- fork the models repository and submit a PR

# Configuration

## set_graph

Given an infrastructure object this API method will create a fully qualified infrastructure graph and validate it.

Creating a fully qualified infrastructure graph requires the following steps:

- process each of the infrastructure instance objects by locating the device and creating a subgraph using the device's edges and substituting the instance name for the device name.
- process each of the infrastructure edges, looking up the instance to determine the max count and the name to be substituted for the device and link the subgraphs to create a complete infrastructure graph

##### Request Body schema: application/json

name | string^[\sa-zA-Z0-9-_()><\[\]]+$ The name of the infrastructure. Globally unique name of an object. It also serves as the primary key for arrays of objects.
description | string A detailed description of the infrastructure.
| Array of objects (Device) An inventory of devices and components.
| Array of objects (Link) An inventory of the links present in the infrastructure edges.
| Array of objects (Instance) An inventory of the device instances present in the infrastructure edges.
| Array of objects (Infrastructure.Edge) An array of edge objects used to connect instance devices and components to other instance devices and components. These edge objects are used to form a fully qualified qualified graph.

### Responses

/set_graph

### Request samples

- Payload

Content type
application/json
`
{

- "name": "string",
- "description": "string",
- "devices":
  [
  - {
    - "name": "string",
    - "description": "string",
    - "components":
      [
      - {
        - "name": "string",
        - "description": "string",
        - "count": 0,
        - "choice": "custom",
        - "custom": { },
        - "device": { },
        - "cpu": { },
        - "npu": { },
        - "nic": { },
        - "memory": { },
        - "port": { }
        }
      ],
    - "links":
      [
      - {
        - "name": "string",
        - "description": "string",
        - "physical":
          {
          - "bandwidth":
            {
            - "choice": "gigabits_per_second",
            - "gigabits_per_second": 0,
            - "gigabytes_per_second": 0,
            - "gigatransfers_per_second": 0
            },
          - "latency":
            {
            - "choice": "ms",
            - "ms": 0,
            - "us": 0,
            - "ns": 0
            }
          }
        }
      ],
    - "edges":
      [
      - {
        - "ep1":
          {
          - "device": "string",
          - "component": "string"
          },
        - "ep2":
          {
          - "device": "string",
          - "component": "string"
          },
        - "scheme": "one2one",
        - "link": "string"
        }
      ]
    }
  ],
- "links":
  [
  - {
    - "name": "string",
    - "description": "string",
    - "physical":
      {
      - "bandwidth":
        {
        - "choice": "gigabits_per_second",
        - "gigabits_per_second": 0,
        - "gigabytes_per_second": 0,
        - "gigatransfers_per_second": 0
        },
      - "latency":
        {
        - "choice": "ms",
        - "ms": 0,
        - "us": 0,
        - "ns": 0
        }
      }
    }
  ],
- "instances":
  [
  - {
    - "name": "string",
    - "description": "string",
    - "device": "string",
    - "count": 0
    }
  ],
- "edges":
  [
  - {
    - "ep1":
      {
      - "instance": "string",
      - "component": "string"
      },
    - "ep2":
      {
      - "instance": "string",
      - "component": "string"
      },
    - "scheme": "one2one",
    - "link": "string"
    }
  ]

}`

### Response samples

- 200
- default

Content type
application/json
`
{

- "warnings":
  [
  - "string"
  ]

}`

## get_graph

This will return the current graph.

##### Request Body schema: application/json

format | string Value: "networkx" The format that the graph will be returned in.

### Responses

/get_graph

### Request samples

- Payload

Content type
application/json
`
{

- "format": "networkx"

}`

### Response samples

- 200
- default

Content type
application/json
`
{

- "choice": "networkx",
- "networkx": "string"

}`

## annotate_graph

Extend the current graph created by the `set_graph` API.

- example: Update specific endpoints with name/value information such as `rank=0`

##### Request Body schema: application/json

choice | string Enum: "nodes" "edges"
| Array of objects (Annotation.Node)
| Array of objects (Annotation.Edge)

### Responses

/annotate_graph

### Request samples

- Payload

Content type
application/json
`
{

- "choice": "nodes",
- "nodes":
  [
  - {
    - "name": "string",
    - "attribute": "string",
    - "value": "string"
    }
  ],
- "edges":
  [
  - {
    - "ep1": "string",
    - "ep2": "string",
    - "attribute": "string",
    - "value": "string"
    }
  ]

}`

### Response samples

- 200
- default

Content type
application/json
`
{

- "warnings":
  [
  - "string"
  ]

}`

# Actions

## query_graph

Query the current fully expanded graph using a declarative query syntax.

- example: Ask the graph for specific endpoints such as those of type `NPU` or `NIC`

##### Request Body schema: application/json

choice | string Enum: "node_filters" "shortest_path_filters"
| Array of objects (QueryNodeFilter)
| Array of objects (QueryShortestPathFilter) Under Review: Proposal to abstract the shortest path interface to the graph. Add shortest path filters to retrive the shortest path between source and destination nodes

### Responses

/query_graph

### Request samples

- Payload

Content type
application/json
`
{

- "choice": "node_filters",
- "node_filters":
  [
  - {
    - "name": "string",
    - "choice": "attribute_filter",
    - "attribute_filter":
      {
      - "name": "string",
      - "operator": "eq",
      - "value": "string",
      - "logic": "and"
      },
    - "id_filter":
      {
      - "operator": "eq",
      - "value": "string",
      - "logic": "and"
      }
    }
  ],
- "shortest_path_filters":
  [
  - {
    - "name": "string",
    - "source": "string",
    - "destination": "string"
    }
  ]

}`

### Response samples

- 200
- default

Content type
application/json
`
{

- "choice": "node_matches",
- "node_matches":
  [
  - {
    - "id": "string",
    - "attributes":
      [
      - {
        - "name": "string",
        - "value": "string"
        }
      ]
    }
  ],
- "shortest_path_matches":
  [
  - {
    - "name": "string",
    - "nodes":
      [
      - "string"
      ]
    }
  ]

}`

# Capabilities

## get_version

### Responses

/capabilities/version

### Response samples

- 200
- default

Content type
application/json
`
{

- "api_spec_version": "",
- "sdk_version": "",
- "app_version": ""

}`