diff --git a/Makefile b/Makefile index 3318d1a..4f2eb82 100644 --- a/Makefile +++ b/Makefile @@ -47,8 +47,12 @@ deploy: ## deploy packages to pypi.org source .venv/bin/activate && \ python3 -m twine upload -u __token__ -p $(PYPI_TOKEN) dist/* +.PHONY: openapi-html +openapi-html: ## generate OpenAPI HTML from artifacts/openapi.yaml using redocly + npx @redocly/cli build-docs artifacts/openapi.yaml -o docs/src/openapi.html + .PHONY: docs -docs: ## generate local documentation to docs/site +docs: openapi-html ## generate local documentation to docs/site source .venv/bin/activate && \ python3 docs/generate_yaml.py && \ python3 -m mkdocs build --config-file docs/mkdocs.yml --site-dir site diff --git a/api/api.yaml b/api/api.yaml index 4295b62..bdea5f3 100644 --- a/api/api.yaml +++ b/api/api.yaml @@ -10,7 +10,8 @@ paths: 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 + - 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 + - resets all the annotations requestBody: required: true content: @@ -80,7 +81,7 @@ paths: content: application/json: schema: - $ref: '../models/graph.yaml#/components/schemas/AnnotateRequest' + $ref: '../models/annotation.yaml#/components/schemas/Annotation' responses: '200': $ref: '../models/request.yaml#/components/responses/Success' diff --git a/artifacts/infragraph.proto b/artifacts/infragraph.proto index 2c5af32..bbfdf5d 100644 --- a/artifacts/infragraph.proto +++ b/artifacts/infragraph.proto @@ -451,95 +451,180 @@ message Warning { repeated string warnings = 1; } -// Request specifying the desired format for the returned graph. +// Configuration controlling which annotations are returned with the graph. +message AnnotationConfig { + + // Selects whether the response includes the full set of annotations or only the user-applied + // (partial) annotations. + AnnotationType annotations = 1; +} + +// Selects the scope of annotations to return on graph elements. +message AnnotationType { + + message Choice { + enum Enum { + unspecified = 0; + full = 1; + partial = 2; + } + } + // Chooses between returning the complete annotation set or only the + // partial (user-applied) annotations. + // - full: include every attribute present on nodes, edges and links. + // - partial: include only attributes added on top of the underlying infrastructure. + optional Choice.Enum choice = 1; + + // Returns every attribute set on graph elements, including those derived from the underlying + // infrastructure. + optional string full = 2; + + // Returns only the annotations that have been explicitly applied on top of the infrastructure, + // excluding immutable infrastructure-derived attributes. + optional string partial = 3; +} + +// The infragraph representation of the current graph, consisting of the infrastructure +// definition and the annotations applied to its nodes, edges and links. +message GraphResponseInfragraph { + + // The infrastructure definition that the graph was built from. + Infrastructure infrastructure = 1; + + // The set of annotations applied to nodes, edges and links of the graph. + Annotation annotations = 2; +} + +// Selects the representation used when returning the graph. +message GraphType { + + message Choice { + enum Enum { + unspecified = 0; + infragraph = 1; + } + } + // The graph representation to return. + // - infragraph: native infrastructure + annotations representation. + optional Choice.Enum choice = 1; +} + +// Request specifying which graph representation to return and how +// annotations should be included in the response. message GraphRequest { - message Format { + message Choice { enum Enum { unspecified = 0; - networkx = 1; + infragraph = 1; + networkx = 2; } } - // The format that the graph will be returned in. - optional Format.Enum format = 1; + // The graph representation to return. + // - infragraph: infrastructure and annotations as a structured object. + // - networkx: a networkx node-link graph serialized as a YAML string. + optional Choice.Enum choice = 1; + + // Annotation configuration applied when returning the graph as an infragraph (infrastructure + // and annotations). + AnnotationConfig infragraph = 2; + + // Annotation configuration applied when returning the graph as a networkx node-link + // YAML string. + AnnotationConfig networkx = 3; } -// The content of the graph response, specifying the format and the serialized graph -// data. -message GraphContent { +// The content of a graph response, returned either as a structured infragraph object +// or as a networkx YAML string depending on the request. +message GraphResponseContent { message Choice { enum Enum { unspecified = 0; - networkx = 1; + infragraph = 1; + networkx = 2; } } - // Specifies the format of the returned graph content. + // The representation contained in this response. + // - infragraph: structured infrastructure and annotations object. + // - networkx: networkx node-link graph serialized as a YAML string. optional Choice.Enum choice = 1; - // This contains the returned graph content formatted as a networkx yaml string. - optional string networkx = 2; + // The graph returned as a structured infragraph (infrastructure plus annotations). + GraphResponseInfragraph infragraph = 2; + + // The graph returned as a networkx node-link graph serialized as a YAML string. + optional string networkx = 3; +} + +// Defines an annotation to be applied to a graph node. +message AnnotationAttribute { + + // The attribute name that will be added to the endpoint. + optional string attribute = 1; + + // The attribute value that will be added to the endpoint. + optional string value = 2; } // Defines an annotation to be applied to a graph node. message AnnotationNode { - // A fully qualified node name that MUST exist in the graph. - // - server.0.xpu.0 - // - server.6.nic.3 - // - switch.2.asic.0 + // Node name that MUST exist or match nodes present in the graph. This supports slicing + // operator and converts to expanded format: + // - server[0]xpu[0] + // - server[0:2] + // - switch optional string name = 1; - // The attribute name that will be added to the endpoint. - optional string attribute = 2; + // An inventory of attributes and values. + repeated AnnotationAttribute attributes = 2; +} - // The attribute value that will be added to the endpoint. - optional string value = 3; +// Defines an annotation to be applied to a graph link. +message AnnotationLink { + + // A fully qualified link name that MUST exist in the graph. + // - pcie + optional string name = 1; + + // An inventory of attributes and values. + repeated AnnotationAttribute attributes = 2; } // Defines an annotation to be applied to a graph edge. message AnnotationEdge { - // A fully qualified endpoint name that MUST exist as part of an edge along with ep2 - // in the graph. - // - server.0.xpu.0 - // - server.6.nic.3 - // - switch.2.asic.0 + // Endpoint name that MUST exist or match edges present in the graph. This supports + // slicing operator and expands to the networkx expanded format: + // - server[0]xpu[0] + // - server[0:2] + // - switch optional string ep1 = 1; - // A fully qualified endpoint name that MUST exist as part of an edge along with ep1 - // in the graph. - // - server.0.xpu.0 - // - server.6.nic.3 - // - switch.2.asic.0 + // Endpoint name that MUST exist or match edges present in the graph. This supports + // slicing operator and expands to the networkx expanded format: + // - server[0]xpu[0] + // - server[0:2] + // - switch optional string ep2 = 2; - // The attribute name that will be added to the edge. - optional string attribute = 3; - - // The attribute value that will be added to the edge. - optional string value = 4; + // An inventory of attributes and values. + repeated AnnotationAttribute attributes = 3; } // Request object specifying which graph elements (nodes or edges) to annotate and the // annotations to apply. -message AnnotateRequest { +message Annotation { - message Choice { - enum Enum { - unspecified = 0; - nodes = 1; - edges = 2; - } - } - // Select whether to annotate nodes or edges.. - optional Choice.Enum choice = 1; + // List of annotations to apply to nodes. + repeated AnnotationNode nodes = 1; - // List of node annotations to apply when the choice is set to nodes. - repeated AnnotationNode nodes = 2; + // List of annotations to apply to edges. + repeated AnnotationEdge edges = 2; - // List of edge annotations to apply when the choice is set to edges. - repeated AnnotationEdge edges = 3; + // List of annotations to apply to links. + repeated AnnotationLink links = 3; } // Represents a generic name and value pair attribute. @@ -744,9 +829,9 @@ message Failure { Error error = 1; } -// The entire fully validated graph content. +// The current graph content, returned in the representation selected by the request. message GraphResponse { - GraphContent graph_content = 1; + GraphResponseContent graph_response_content = 1; } // Answer to the query request. @@ -772,7 +857,7 @@ message GetGraphRequest { GraphRequest graph_request = 1; } message GetGraphResponse { - GraphContent graph_content = 1; + GraphResponseContent graph_response_content = 1; } @@ -785,7 +870,7 @@ message QueryGraphResponse { message AnnotateGraphRequest { - AnnotateRequest annotate_request = 1; + Annotation annotation = 1; } message AnnotateGraphResponse { Warning warning = 1; @@ -814,6 +899,7 @@ service Openapi { // - 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 + // - resets all the annotations rpc SetGraph(SetGraphRequest) returns (SetGraphResponse); // streaming version of the rpc SetGraph rpc streamSetGraph(stream Data) returns (SetGraphResponse); diff --git a/artifacts/openapi.yaml b/artifacts/openapi.yaml index a9b44c2..8851519 100644 --- a/artifacts/openapi.yaml +++ b/artifacts/openapi.yaml @@ -35,12 +35,15 @@ paths: - Configuration operationId: set_graph x-stream: client - description: |- - 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 + description: "Given an infrastructure object this API method will create a fully\ + \ qualified infrastructure graph and validate it.\n\nCreating a fully qualified\ + \ infrastructure graph requires the following steps:\n - 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.\n - 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 \n - resets all the annotations" requestBody: required: true content: @@ -113,7 +116,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/AnnotateRequest' + $ref: '#/components/schemas/Annotation' responses: '200': $ref: '#/components/responses/Success' @@ -157,11 +160,11 @@ components: $ref: '#/components/schemas/Error' GraphResponse: description: |- - The entire fully validated graph content. + The current graph content, returned in the representation selected by the request. content: application/json: schema: - $ref: '#/components/schemas/GraphContent' + $ref: '#/components/schemas/GraphResponseContent' QueryResponse: description: |- Answer to the query request. @@ -741,39 +744,152 @@ components: items: type: string x-field-uid: 1 - GraphRequest: + Annotation.Config: + type: object description: |- - Request specifying the desired format for the returned graph. + Configuration controlling which annotations are returned with the graph. + properties: + annotations: + description: |- + Selects whether the response includes the full set of annotations or only the user-applied (partial) annotations. + $ref: '#/components/schemas/Annotation.Type' + x-field-uid: 1 + Annotation.Type: type: object + description: |- + Selects the scope of annotations to return on graph elements. properties: - format: + choice: description: |- - The format that the graph will be returned in. + Chooses between returning the complete annotation set or only the + partial (user-applied) annotations. + - full: include every attribute present on nodes, edges and links. + - partial: include only attributes added on top of the underlying infrastructure. type: string x-field-uid: 1 x-enum: - networkx: + full: x-field-uid: 1 + partial: + x-field-uid: 2 enum: - - networkx - GraphContent: + - full + - partial + full: + type: string + description: |- + Returns every attribute set on graph elements, including those derived from the underlying infrastructure. + x-field-uid: 2 + partial: + type: string + description: |- + Returns only the annotations that have been explicitly applied on top of the infrastructure, excluding immutable infrastructure-derived attributes. + x-field-uid: 3 + GraphResponse.Infragraph: + type: object description: |- - The content of the graph response, specifying the format and the serialized graph data. + The infragraph representation of the current graph, consisting of the infrastructure definition and the annotations applied to its nodes, edges and links. + properties: + infrastructure: + description: |- + The infrastructure definition that the graph was built from. + $ref: '#/components/schemas/Infrastructure' + x-field-uid: 1 + annotations: + description: |- + The set of annotations applied to nodes, edges and links of the graph. + $ref: '#/components/schemas/Annotation' + x-field-uid: 2 + Graph.Type: type: object + description: |- + Selects the representation used when returning the graph. properties: choice: description: |- - Specifies the format of the returned graph content. + The graph representation to return. + - infragraph: native infrastructure + annotations representation. type: string x-field-uid: 1 x-enum: + infragraph: + x-field-uid: 1 + enum: + - infragraph + GraphRequest: + description: |- + Request specifying which graph representation to return and how + annotations should be included in the response. + type: object + properties: + choice: + description: |- + The graph representation to return. + - infragraph: infrastructure and annotations as a structured object. + - networkx: a networkx node-link graph serialized as a YAML string. + type: string + x-field-uid: 1 + x-enum: + infragraph: + x-field-uid: 1 networkx: + x-field-uid: 2 + enum: + - infragraph + - networkx + infragraph: + description: |- + Annotation configuration applied when returning the graph as an infragraph (infrastructure and annotations). + $ref: '#/components/schemas/Annotation.Config' + x-field-uid: 2 + networkx: + description: |- + Annotation configuration applied when returning the graph as a networkx node-link YAML string. + $ref: '#/components/schemas/Annotation.Config' + x-field-uid: 3 + GraphResponseContent: + type: object + description: |- + The content of a graph response, returned either as a structured infragraph object or as a networkx YAML string depending on the request. + properties: + choice: + description: |- + The representation contained in this response. + - infragraph: structured infrastructure and annotations object. + - networkx: networkx node-link graph serialized as a YAML string. + type: string + x-field-uid: 1 + x-enum: + infragraph: x-field-uid: 1 + networkx: + x-field-uid: 2 enum: + - infragraph - networkx + infragraph: + description: |- + The graph returned as a structured infragraph (infrastructure plus annotations). + $ref: '#/components/schemas/GraphResponse.Infragraph' + x-field-uid: 2 networkx: description: |- - This contains the returned graph content formatted as a networkx yaml string. + The graph returned as a networkx node-link graph serialized as a YAML string. + type: string + x-field-uid: 3 + Annotation.Attribute: + description: |- + Defines an annotation to be applied to a graph node. + type: object + properties: + attribute: + description: |- + The attribute name that will be added to the endpoint. + type: string + x-field-uid: 1 + value: + description: |- + The attribute value that will be added to the endpoint. type: string x-field-uid: 2 Annotation.Node: @@ -783,22 +899,37 @@ components: properties: name: description: |- - A fully qualified node name that MUST exist in the graph. - - server.0.xpu.0 - - server.6.nic.3 - - switch.2.asic.0 + Node name that MUST exist or match nodes present in the graph. This supports slicing operator and converts to expanded format: + - server[0]xpu[0] + - server[0:2] + - switch type: string x-field-uid: 1 - attribute: + attributes: description: |- - The attribute name that will be added to the endpoint. - type: string + An inventory of attributes and values. + type: array + items: + $ref: '#/components/schemas/Annotation.Attribute' x-field-uid: 2 - value: + Annotation.Link: + description: |- + Defines an annotation to be applied to a graph link. + type: object + properties: + name: description: |- - The attribute value that will be added to the endpoint. + A fully qualified link name that MUST exist in the graph. + - pcie type: string - x-field-uid: 3 + x-field-uid: 1 + attributes: + description: |- + An inventory of attributes and values. + type: array + items: + $ref: '#/components/schemas/Annotation.Attribute' + x-field-uid: 2 Annotation.Edge: description: |- Defines an annotation to be applied to a graph edge. @@ -806,61 +937,52 @@ components: properties: ep1: description: |- - A fully qualified endpoint name that MUST exist as part of an edge along with ep2 in the graph. - - server.0.xpu.0 - - server.6.nic.3 - - switch.2.asic.0 + Endpoint name that MUST exist or match edges present in the graph. This supports slicing operator and expands to the networkx expanded format: + - server[0]xpu[0] + - server[0:2] + - switch type: string x-field-uid: 1 ep2: description: |- - A fully qualified endpoint name that MUST exist as part of an edge along with ep1 in the graph. - - server.0.xpu.0 - - server.6.nic.3 - - switch.2.asic.0 + Endpoint name that MUST exist or match edges present in the graph. This supports slicing operator and expands to the networkx expanded format: + - server[0]xpu[0] + - server[0:2] + - switch type: string x-field-uid: 2 - attribute: + attributes: description: |- - The attribute name that will be added to the edge. - type: string + An inventory of attributes and values. + type: array + items: + $ref: '#/components/schemas/Annotation.Attribute' x-field-uid: 3 - value: - description: |- - The attribute value that will be added to the edge. - type: string - x-field-uid: 4 - AnnotateRequest: + Annotation: description: |- Request object specifying which graph elements (nodes or edges) to annotate and the annotations to apply. type: object properties: - choice: - description: |- - Select whether to annotate nodes or edges.. - type: string - x-field-uid: 1 - x-enum: - nodes: - x-field-uid: 1 - edges: - x-field-uid: 2 - enum: - - nodes - - edges nodes: description: |- - List of node annotations to apply when the choice is set to nodes. + List of annotations to apply to nodes. type: array items: $ref: '#/components/schemas/Annotation.Node' - x-field-uid: 2 + x-field-uid: 1 edges: type: array description: |- - List of edge annotations to apply when the choice is set to edges. + List of annotations to apply to edges. items: $ref: '#/components/schemas/Annotation.Edge' + x-field-uid: 2 + links: + type: array + description: |- + List of annotations to apply to links. + items: + $ref: '#/components/schemas/Annotation.Link' x-field-uid: 3 NameValue: description: |- diff --git a/docs/src/openapi.html b/docs/src/openapi.html index f4ec73b..f1357e6 100644 --- a/docs/src/openapi.html +++ b/docs/src/openapi.html @@ -555,7 +555,8 @@

Contributions

Creating a fully qualified infrastructure graph requires the following steps:

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.

@@ -569,20 +570,26 @@

Contributions

may return a list of detailed warnings.

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "devices": [
    ],
  • "links": [
    ],
  • "instances": [
    ],
  • "edges": [
    ]
}

Response samples

Content type
application/json
{
  • "warnings": [
    ]
}

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

Request Body schema: application/json
choice
string
Enum: "infragraph" "networkx"

The graph representation to return.

+
    +
  • infragraph: infrastructure and annotations as a structured object.
    • +
  • networkx: a networkx node-link graph serialized as a YAML string.
    • +
+
object (Annotation.Config)

Configuration controlling which annotations are returned with the graph.

+
object (Annotation.Config)

Configuration controlling which annotations are returned with the graph.

+

Responses

Request samples

Content type
application/json
{
  • "format": "networkx"
}

Response samples

Content type
application/json
{
  • "choice": "networkx",
  • "networkx": "string"
}

annotate_graph

Extend the current graph created by the set_graph API.

+

Request samples

Content type
application/json
{
  • "choice": "infragraph",
  • "infragraph": {
    },
  • "networkx": {
    }
}

Response samples

Content type
application/json
{
  • "choice": "infragraph",
  • "infragraph": {
    },
  • "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"

Select whether to annotate nodes or edges..

-
Array of objects (Annotation.Node)

List of node annotations to apply when the choice is set to nodes.

-
Array of objects (Annotation.Edge)

List of edge annotations to apply when the choice is set to edges.

+
Request Body schema: application/json
Array of objects (Annotation.Node)

List of annotations to apply to nodes.

+
Array of objects (Annotation.Edge)

List of annotations to apply to edges.

+
Array of objects (Annotation.Link)

List of annotations to apply to links.

Responses

Request samples

Content type
application/json
{
  • "choice": "nodes",
  • "nodes": [
    ],
  • "edges": [
    ]
}

Response samples

Content type
application/json
{
  • "warnings": [
    ]
}

Actions

query_graph

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

+

Request samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ],
  • "links": [
    ]
}

Response samples

Content type
application/json
{
  • "warnings": [
    ]
}

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 XPU or NIC
@@ -596,7 +603,7 @@

Contributions

Response samples

Content type
application/json
{
  • "api_spec_version": "",
  • "sdk_version": "",
  • "app_version": ""
}