api-doc.yaml

openapi: 3.0.0
servers:
  - url: ../
    description: current system
info:
  title: Resoto Core REST API
  version: V1
tags:
  - name: graph_search
    description: Endpoints to search all sections of the graph.
  - name: graph_management
    description: Create, update wipe or delete a complete graph.
  - name: node_management
    description: Create, update, delete and get a node in the graph.
  - name: model
    description: Endpoints to maintain the schema and model of the entities inside a graph.
  - name: config
    description: Endpoints to maintain configuration data.
  - name: config_validation
    description: Endpoints to define how configs should be validated.
  - name: cli
    description: Endpoints to evaluate and execute cli commands.
  - name: subscriptions
    description: Endpoints to manipulate event subscriptions.
  - name: work_queue
    description: Endpoints to attach to the work queue.
  - name: certificate
    description: Endpoints to access the certificate authority as well as signing functionality.
  - name: system
    description: Endpoints to get information about the system.
  - name: debug
    description: Endpoints to debug the system.

paths:

  # region model
  /model:
    get:
      summary: "Get the currently defined model."
      tags:
        - model
      responses:
        "200":
          description: "The list of all kinds."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kind"
    patch:
      summary: "Add or update the current defined model."
      tags:
        - model
      requestBody:
        description: "Complete model or part of the model."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Kind"
      responses:
        "200":
          description: "OK if the model is updated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kind"
        "400":
          description: "Message that explains the error"
          content:
            text/plain:
              schema:
                type: string
  /model/uml:
    get:
      summary: "Get the currently defined model as svg uml image."
      tags:
        - model
      parameters:
        - name: output
          description: The output format.
          in: query
          schema:
            type: string
            enum:
              - svg
              - png
            default: svg
          required: false
        - name: show
          description: comma separated list of resources to show. Entries can be regexps.
          in: query
          schema:
            type: string
          required: false
          explode: false
          example: aws_ec2_instance,gcp.*
        - name: hide
          description: |
            comma separated list of resources to hide. Entries can be regexps.
            hide takes precedence over show.
          in: query
          schema:
            type: string
          required: false
          explode: false
          example: aws_ec2_instance,gcp.*
        - name: with_inheritance
          description: Include inheritance relations in the model.
          in: query
          schema:
            type: boolean
            default: true
        - name: with_base_classes
          description: Include all base classes of visible entries
          in: query
          schema:
            type: boolean
            default: true
        - name: with_subclasses
          description: Include all descendant classes of visible entries
          in: query
          schema:
            type: boolean
            default: false
        - name: dependency
          description: |
            comma separated list of dependency relationships.
          in: query
          schema:
            type: string
          required: false
          explode: false
          example: default
        - name: with_predecessors
          description: Include all predecessors of selected entries
          in: query
          schema:
            type: boolean
            default: false
        - name: with_successors
          description: Include all successors of selected entries
          in: query
          schema:
            type: boolean
            default: false
        - name: with_properties
          description: Show properties of selected entries
          in: query
          schema:
            type: boolean
            default: true
        - name: link_classes
          description: Add anchor links to classes.
          in: query
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: "Returns the model as uml diagram in svg format"
  # endregion

  # region graph management
  /graph:
    get:
      summary: "List all graphs"
      tags:
        - graph_management
      responses:
        "200":
          description: "The names of all graphs"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: [ "main", "test" ]
  /graph/{graph_id}:
    get:
      summary: "Get root of a specific graph"
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "The graph with the root node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "404":
          description: "The graph does not exist"
    post:
      summary: "Create a new graph"
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "The created graph with the root node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
    delete:
      summary: "Delete an existing graph"
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: truncate
          in: query
          schema:
            type: boolean
          description: "If this parameter is set, leave the graph definition, but wipe the data."
      responses:
        "200":
          description: "Ok when the delete operation was successful"
          content:
            text/plain:
              example: "Graph deleted."

  /graph/{graph_id}/merge:
    post:
      summary: "Merge a given graph with the existing graph under marked merge nodes."
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
      requestBody:
        description:
          "The graph is sent as newline delimited json, where each line holds a document, which is either a node or an edge."
        required: true
        content:
          application/x-ndjson:
            schema:
              oneOf:
                - $ref: "#/components/schemas/NodeInGraph"
                - $ref: "#/components/schemas/Edge"
            example:
              # TODO: is there a way to show ndjson instead of json?
              [
                { "id": "a", "data": { "kind": "loadbalancer", "ip": "1.2.3.4", "mathod": "roundrobin" } },
                { "id": "b", "data": { "kind": "compute_instance", "machine_type": "gt-5", "cores": 24 } },
                { "from": "a", "to": "b", "edge_type": "default" },
                { "id": "c", "data": { "kind": "compute_instance", "machine_type": "gt-5", "cores": 24 } },
                { "from": "a", "to": "c", "edge_type": "default" }
              ]
      responses:
        "200":
          description: "Return a summary of actions that has been applied."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GraphUpdate"
  /graph/{graph_id}/batch/merge:
    post:
      summary: "Merge a given graph with the existing graph under marked merge nodes as batch update."
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Merge a given graph with the existing graph under marked merge nodes as batch update.
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: batch_id
          in: query
          description: >
            A batch identifier is a string that uniquely identifies the batch update.
            If this parameter is omitted, a new batch identifier is created automatically.
            The resulting batch identifier can be retrieved via the response message.
          required: false
          schema:
            default: null
            type: string
      requestBody:
        description:
          "The graph is sent as newline delimited json, where each line holds a document, which is either a node or an edge."
        required: true
        content:
          application/x-ndjson:
            schema:
              oneOf:
                - $ref: "#/components/schemas/NodeInGraph"
                - $ref: "#/components/schemas/Edge"
            example:
              # TODO: is there a way to show ndjson instead of json?
              [
                { "id": "a", "data": { "kind": "loadbalancer", "ip": "1.2.3.4", "mathod": "roundrobin" } },
                { "id": "b", "data": { "kind": "compute_instance", "machine_type": "gt-5", "cores": 24 } },
                { "from": "a", "to": "b", "edge_type": "default" },
                { "id": "c", "data": { "kind": "compute_instance", "machine_type": "gt-5", "cores": 24 } },
                { "from": "a", "to": "c", "edge_type": "default" }
              ]
      responses:
        "200":
          description: "Return a summary of actions that has been applied."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GraphUpdate"
  /graph/{graph_id}/batch:
    get:
      summary: "Get a list of all running batch updates"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Get a list of all running batch updates.
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Ok message"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchUpdate"
  /graph/{graph_id}/batch/{batch_id}:
    post:
      summary: "Commit a batch update"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Commit a batch update.
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: batch_id
          in: path
          description: "A batch identifier is a string that uniquely identifies the batch update."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Ok message"
          content:
            application/json:
              schema:
                type: string
                example: "Batch committed."
    delete:
      summary: "Abort a batch update"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Abort a batch update.
      tags:
        - graph_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: batch_id
          in: path
          description: "A batch identifier is a string that uniquely identifies the batch update."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Ok message"
          content:
            application/json:
              schema:
                type: string
                example: "Batch aborted."
  # endregion

  # region node management
  /graph/{graph_id}/nodes:
    patch:
      summary: "Patch a list of nodes."
      description: |
        Apply a patch on existing nodes. Non existing nodes are not updated!
        Consider to stream the request body as new line delimited json (application/x-ndjson).
      tags:
        - node_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
      requestBody:
        description: "The partial object data to patch."
        content:
          application/x-ndjson:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The identifier of the node.
                reported:
                  type: object
                  additionalProperties: true
                desired:
                  type: object
                  additionalProperties: true
                metadata:
                  type: object
                  additionalProperties: true

          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: The identifier of the node.
                  reported:
                    type: object
                    additionalProperties: true
                  desired:
                    type: object
                    additionalProperties: true
                  metadata:
                    type: object
                    additionalProperties: true




      responses:
        "200":
          description: "Return the patched node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
  /graph/{graph_id}/node/{node_id}/under/{parent_node_id}:
    post:
      summary: "Create a new node under the given parent node"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Create a new node under the given parent node.
      tags:
        - node_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: node_id
          in: path
          description: "The identifier of the node"
          required: true
          schema:
            type: string
        - name: parent_node_id
          in: path
          description: "The identifier of the parent node"
          required: true
          schema:
            type: string
      requestBody:
        description: "The node document to create."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Node"
      responses:
        "200":
          description: "Return the created node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
  /graph/{graph_id}/node/{node_id}:
    get:
      summary: "Get a node with the given node id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Get a node with the given node id
      tags:
        - node_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: node_id
          in: path
          description: "The identifier of the node"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Return the defined node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
    patch:
      summary: "Update a node with the given node id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Update a node with the given node id
      tags:
        - node_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: node_id
          in: path
          description: "The identifier of the node"
          required: true
          schema:
            type: string
      requestBody:
        description: "The partial object data to patch."
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: "Return the patched node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
    delete:
      summary: "Delete a node with the given node id."
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Delete a node with the given node id.
      tags:
        - node_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: node_id
          in: path
          description: "The identifier of the node"
          required: true
          schema:
            type: string
      responses:
        "204":
          description: "Node is deleted"
  /graph/{graph_id}/node/{node_id}/section/{section}:
    patch:
      summary: "Patch a node with the given node id in given section"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Patch a node with the given node id in given section
      tags:
        - node_management
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: node_id
          in: path
          description: "The identifier of the node"
          required: true
          schema:
            type: string
        - name: section
          in: path
          description: "The identifier of the section"
          required: true
          schema:
            type: string
            enum:
              - reported
              - desired
              - metadata
      requestBody:
        description: "The partial object data to patch."
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: "Return the patched node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
  # endregion

  # region search graph
  /graph/{graph_id}/search/raw:
    post:
      summary: "Transform the search into the raw database search"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Show the underlying raw search.
      tags:
        - debug
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: section
          in: query
          description: "The name of the section used for all property paths. If not defined root is assumed."
          required: false
          schema:
            type: string
            enum:
              - reported
              - desired
              - metadata
      requestBody:
        description: "The search to perform"
        content:
          text/plain:
            schema:
              type: string
              example: is(graph_root) and reported.name=="root" -->
      responses:
        "200":
          description: "Returns the search as performed by the database."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RawQuery"
  /graph/{graph_id}/search/list:
    post:
      summary: "Search the graph and return all nodes as list (this will not contain any edges)"
      description: |
        Search the graph and return the matching nodes as list.
        A section can be defined (defaults to `/` == root) to interpret relative property paths.
        Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)
      tags:
        - graph_search
      parameters:
        - name: graph_id
          in: path
          example: resoto
          description: "The identifier of the graph"
          required: true
          schema:
            type: string
        - name: section
          in: query
          description: "The name of the section used for all property paths. If not defined root is assumed."
          required: false
          schema:
            type: string
            enum:
              - reported
              - desired
              - metadata
        - name: count
          in: query
          description: "Optional parameter to get a Ck-Element-Count header which returns the number of returned json elements"
          required: false
          schema:
            type: boolean
            default: true
      requestBody:
        description: "The search to perform"
        content:
          text/plain:
            schema:
              type: string
              example: is(graph_root) and reported.name=="root" -->
      responses:
        "200":
          description: "The result of this search in the defined format"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Node"
            application/x-ndjson:
              schema:
                $ref: "#/components/schemas/Node"
              example: |
                {"type": "node", "id": "root", "revision": "123", "reported": {"kind": "graph_root", "id": "root", "tags": {}, "name": "root"}}
                {"type": "node", "id": "cloud_id",  "revision": "12", "reported": {"kind": "cloud", "id": "onelogin", "tags": {}, "name": "onelogin", "ctime": "2021-12-14T08:49:52Z", "age": "6d7h"}}
                {"type": "edge", "from": "root", "to": "cloud_id", "edge_type": "default"}
            text/plain:
              example: |
                reported:
                  kind: graph_root
                  id: root
                  tags: {}
                  name: root
                metadata:
                  cleaned: false
                  phantom: true
                  protected: false
            application/yaml:
              example: |
                id: root
                type: node
                revision: _daGy-Bu---
                reported:
                    kind: graph_root
                    id: root
                    tags: { }
                    name: root
                metadata:
                    python_type: resotolib.baseresources.GraphRoot
                    cleaned: false
                    phantom: true
                    protected: false
                kinds:
                    - graph_root
                ---
                id: 2RZlTX9yzeBwTNT_H1KZVA
                type: node
                revision: _daGy-Bi---
                reported:
                    kind: cloud
                    id: onelogin
                    tags: { }
                    name: onelogin
                    ctime: '2021-12-14T08:49:52Z'
                    age: 6d7h
                metadata:
                    python_type: resotolib.baseresources.Cloud
                    cleaned: false
                    phantom: false
                    protected: false
                    descendant_summary:
                        onelogin_account: 1
                        onelogin_region: 1
                        onelogin_user: 1034
                    descendant_count: 1036
                ancestors:
                    cloud:
                        reported:
                            name: onelogin
                            id: onelogin
                kinds:
                    - cloud
                    - base_cloud
                    - resource
                ---
                type: edge
                from: root
                to: 2RZlTX9yzeBwTNT_H1KZVA
                edge_type: default

            application/vnd.graphml+xml:
              example: |
                <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
                    <key id="d4" for="node" attr.name="age" attr.type="string"/>
                    <key id="d3" for="node" attr.name="ctime" attr.type="string"/>
                    <key id="d2" for="node" attr.name="name" attr.type="string"/>
                    <key id="d1" for="node" attr.name="id" attr.type="string"/>
                    <key id="d0" for="node" attr.name="kind" attr.type="string"/>
                    <graph edgedefault="directed">
                        <node id="root">
                            <data key="d0">graph_root</data>
                            <data key="d1">root</data>
                            <data key="d2">root</data>
                        </node>
                        <node id="cloud_id">
                            <data key="d0">cloud</data>
                            <data key="d1">onelogin</data>
                            <data key="d2">onelogin</data>
                            <data key="d3">2021-12-14T08:49:52Z</data>
                            <data key="d4">6d7h</data>
                        </node>
                        <edge source="root" target="cloud_id"/>
                    </graph>
                </graphml>

            application/vnd.cytoscape+json:
              example: |
                {
                    "data": [ ],
                    "directed": true,
                    "elements": {
                        "edges": [
                            {
                                "data": {
                                    "source": "root",
                                    "target": "cloud_id"
                                }
                            }
                        ],
                        "nodes": [
                            {
                                "data": {
                                    "id": "root",
                                    "kind": "graph_root",
                                    "name": "root",
                                    "tags": { },
                                    "value": "root"
                                }
                            },
                            {
                                "data": {
                                    "age": "6d7h",
                                    "ctime": "2021-12-14T08:49:52Z",
                                    "id": "onelogin",
                                    "kind": "cloud",
                                    "name": "onelogin",
                                    "tags": { },
                                    "value": "cloud_id"
                                }
                            }
                        ]
                    },
                    "multigraph": false
                }
            text/vnd.graphviz:
              example: |
                digraph {
                rankdir=LR
                overlap=false
                splines=true
                node [shape=Mrecord colorscheme=paired12]
                edge [arrowsize=0.5]
                  "root" [label="root|graph_root", style=filled fillcolor=1];
                  "2RZlTX9yzeBwTNT_H1KZVA" [label="onelogin|cloud", style=filled fillcolor=2];
                  "root" -> "2RZlTX9yzeBwTNT_H1KZVA"
                  subgraph "graph_root" {
                    "root"
                    "2RZlTX9yzeBwTNT_H1KZVA"
                  }
                }

  /graph/{graph_id}/search/graph:
    post:
      summary: "Search the graph and return the resulting graph."
      description: |
        Search the graph and return the matching nodes including the traversed edges.
        The resulting data can be interpreted as a graph.
        A section can be defined (defaults to `/` == root) to interpret relative property paths.
        Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)
      tags:
        - graph_search
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: section
          in: query
          description: "The name of the section used for all property paths. If not defined root is assumed."
          required: false
          schema:
            type: string
            enum:
              - reported
              - desired
              - metadata
        - name: count
          in: query
          description: "Optional parameter to get a Ck-Element-Count header which returns the number of returned json elements"
          required: false
          schema:
            type: boolean
            default: true
        - name: search_timeout
          in: query
          description: "Optional duration the search is allowed to run."
          required: false
          schema:
            type: string
            example: "30s"
      requestBody:
        description: "The search to perform"
        content:
          text/plain:
            schema:
              type: string
              example: is(graph_root) and reported.name=="root" -->
      responses:
        "200":
          description: "The result of this search in the defined format"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Node"
            application/x-ndjson:
              schema:
                $ref: "#/components/schemas/Node"
              example: |
                {"type": "node", "id": "root", "revision": "123", "reported": {"kind": "graph_root", "id": "root", "tags": {}, "name": "root"}}
                {"type": "node", "id": "cloud_id",  "revision": "12", "reported": {"kind": "cloud", "id": "onelogin", "tags": {}, "name": "onelogin", "ctime": "2021-12-14T08:49:52Z", "age": "6d7h"}}
                {"type": "edge", "from": "root", "to": "cloud_id", "edge_type": "default"}
            text/plain:
              example: |
                reported:
                  kind: graph_root
                  id: root
                  tags: {}
                  name: root
                metadata:
                  cleaned: false
                  phantom: true
                  protected: false
            application/yaml:
              example: |
                id: root
                type: node
                revision: _daGy-Bu---
                reported:
                    kind: graph_root
                    id: root
                    tags: { }
                    name: root
                metadata:
                    python_type: resotolib.baseresources.GraphRoot
                    cleaned: false
                    phantom: true
                    protected: false
                kinds:
                    - graph_root
                ---
                id: 2RZlTX9yzeBwTNT_H1KZVA
                type: node
                revision: _daGy-Bi---
                reported:
                    kind: cloud
                    id: onelogin
                    tags: { }
                    name: onelogin
                    ctime: '2021-12-14T08:49:52Z'
                    age: 6d7h
                metadata:
                    python_type: resotolib.baseresources.Cloud
                    cleaned: false
                    phantom: false
                    protected: false
                    descendant_summary:
                        onelogin_account: 1
                        onelogin_region: 1
                        onelogin_user: 1034
                    descendant_count: 1036
                ancestors:
                    cloud:
                        reported:
                            name: onelogin
                            id: onelogin
                kinds:
                    - cloud
                    - base_cloud
                    - resource
                ---
                type: edge
                from: root
                to: 2RZlTX9yzeBwTNT_H1KZVA
                edge_type: default

            application/vnd.graphml+xml:
              example: |
                <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
                    <key id="d4" for="node" attr.name="age" attr.type="string"/>
                    <key id="d3" for="node" attr.name="ctime" attr.type="string"/>
                    <key id="d2" for="node" attr.name="name" attr.type="string"/>
                    <key id="d1" for="node" attr.name="id" attr.type="string"/>
                    <key id="d0" for="node" attr.name="kind" attr.type="string"/>
                    <graph edgedefault="directed">
                        <node id="root">
                            <data key="d0">graph_root</data>
                            <data key="d1">root</data>
                            <data key="d2">root</data>
                        </node>
                        <node id="cloud_id">
                            <data key="d0">cloud</data>
                            <data key="d1">onelogin</data>
                            <data key="d2">onelogin</data>
                            <data key="d3">2021-12-14T08:49:52Z</data>
                            <data key="d4">6d7h</data>
                        </node>
                        <edge source="root" target="cloud_id"/>
                    </graph>
                </graphml>

            application/vnd.cytoscape+json:
              example: |
                {
                    "data": [ ],
                    "directed": true,
                    "elements": {
                        "edges": [
                            {
                                "data": {
                                    "source": "root",
                                    "target": "cloud_id"
                                }
                            }
                        ],
                        "nodes": [
                            {
                                "data": {
                                    "id": "root",
                                    "kind": "graph_root",
                                    "name": "root",
                                    "tags": { },
                                    "value": "root"
                                }
                            },
                            {
                                "data": {
                                    "age": "6d7h",
                                    "ctime": "2021-12-14T08:49:52Z",
                                    "id": "onelogin",
                                    "kind": "cloud",
                                    "name": "onelogin",
                                    "tags": { },
                                    "value": "cloud_id"
                                }
                            }
                        ]
                    },
                    "multigraph": false
                }
            text/vnd.graphviz:
              example: |
                digraph {
                rankdir=LR
                overlap=false
                splines=true
                node [shape=Mrecord colorscheme=paired12]
                edge [arrowsize=0.5]
                  "root" [label="root|graph_root", style=filled fillcolor=1];
                  "2RZlTX9yzeBwTNT_H1KZVA" [label="onelogin|cloud", style=filled fillcolor=2];
                  "root" -> "2RZlTX9yzeBwTNT_H1KZVA"
                  subgraph "graph_root" {
                    "root"
                    "2RZlTX9yzeBwTNT_H1KZVA"
                  }
                }

  /graph/{graph_id}/search/aggregate:
    post:
      summary: "Search the aggregate function on the specified graph and return the aggregation result."
      description: |
        Search and aggregate the graph and return the resulting aggregated data.
        A section can be defined (defaults to `/` == root) to interpret relative property paths.
        Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)
      tags:
        - graph_search
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: section
          in: query
          description: "The name of the section used for all property paths. If not defined root is assumed."
          required: false
          schema:
            type: string
            enum:
              - reported
              - desired
              - metadata
      requestBody:
        description: "The aggregation search to perform"
        content:
          text/plain:
            schema:
              type: string
              example: |
                aggregate(reported.kind: sum(1) as nodes): is(node)
      responses:
        "200":
          description: "The result of this search in the defined format"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Aggregated"
            application/x-ndjson:
              schema:
                $ref: "#/components/schemas/Aggregated"
  /graph/{graph_id}/search/explain:
    post:
      summary: "Explain the search execution plan"
      description: |
        Explain the runtime characteristics of a search without performing the search.
        A section can be defined (defaults to `/` == root) to interpret relative property paths.
        Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)

      tags:
        - graph_search
      parameters:
        - name: graph_id
          in: path
          description: "The identifier of the graph"
          example: resoto
          required: true
          schema:
            type: string
        - name: section
          in: query
          description: "The name of the section used for all property paths. If not defined root is assumed."
          required: false
          schema:
            type: string
            enum:
              - reported
              - desired
              - metadata
      requestBody:
        description: "The search to perform"
        content:
          text/plain:
            schema:
              type: string
              example: is(graph_root) and reported.name=="root" -->
      responses:
        "200":
          description: "The execution plan of the database"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EstimatedSearchCost"
  # endregion

  # region events

  /analytics:
    post:
      summary: "Send analytics events to the server"
      description: |
          Send analytics events to the server.
          The server will either drop or forward the event based on the user defined settings.
      tags:
        - system
      requestBody:
        description: "The analytics events to send"
        content:
          application/json:
            schema:
                type: array
                items:
                  $ref: "#/components/schemas/AnalyticsEvent"
      responses:
        "204":
          description: "The events were accepted"

  /events:
    get:
      summary: "[WebSocket] Register as event listener and receive all events."
      description:
        ## WebSocket Endpoint
        The client needs to send all the required headers for a ws connection
        and has to handle the websocket protocol.<br/>
        **Note this can not be tested from within swagger!**

      parameters:
        - name: show
          in: query
          description: "All events to show as a comma separated list"
          required: false
          explode: false
          schema:
            type: string
      tags:
        - system
      responses:
        default:
          description: ""
  # endregion

  # region subscriptions

  /subscribers:
    get:
      summary: "List all subscriptions"
      description: "Get all subscriptions of all subscribers in the system"
      tags:
        - subscriptions
      responses:
        "200":
          description: "The list of all subscribers with all subscriptions"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Subscriber"

  /subscribers/for/{event_type}:
    get:
      summary: "List all subscribers for a given event type"
      description: "Get all subscriptions of registered subscribers"
      tags:
        - subscriptions
      parameters:
        - name: event_type
          in: path
          description: "The type of message"
          required: true
          schema:
            type: string

      responses:
        "200":
          description: "The list of all subscribers which are subscribed"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Subscriber"

  /subscriber/{subscriber_id}:
    get:
      summary: "Get subscriber by id"
      description: "Get the subscriber with a defined id."
      tags:
        - subscriptions
      parameters:
        - name: subscriber_id
          in: path
          description: "The identifier of the subscriber"
          required: true
          schema:
            type: string

      responses:
        "200":
          description: "The subscriber"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscriber"
        "404":
          description: "No subscriber found"
          content:
            text/plain:
              schema:
                type: string
                example: No subscriber with this id
    put:
      summary: "Define subscriber with all subscriptions"
      description: |
        Define or redefine a subscriber with all subscriptions.
        In case the subscriber does not exist, it is created.
        In case the subscriber exist, all subscriptions get replaced.
      tags:
        - subscriptions
      parameters:
        - name: subscriber_id
          in: path
          description: "The identifier of the subscriber"
          required: true
          schema:
            type: string
      requestBody:
        description: "The list of all subscriptions."
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Subscription"
      responses:
        "200":
          description: "The subscriber"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscriber"
    delete:
      summary: "Delete by id"
      description: "Delete the subscriber with a defined id."
      tags:
        - subscriptions
      parameters:
        - name: subscriber_id
          in: path
          description: "The identifier of the subscriber"
          required: true
          schema:
            type: string

      responses:
        "204":
          description: "no content"

  /subscriber/{subscriber_id}/{event_type}:
    post:
      summary: "Add subscription to subscriber"
      description: "Add a specific subscription to a subscriber."
      tags:
        - subscriptions
      parameters:
        - name: subscriber_id
          in: path
          description: "The identifier of the subscriber"
          required: true
          schema:
            type: string
        - name: event_type
          in: path
          description: "The action event type."
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          required: false
          description: |
            This is the duration in seconds this subscriber has time to execute the action.
            After this time the sender assumes a failure and rejects the result of this actor.
          schema:
            type: number
            default: 60
        - name: wait_for_completion
          in: query
          required: false
          description: |
            If an action is sent to this subscriber, the event sender should wait until this
            subscriber has processed the message and send a done message.
            This is the expected behaviour of every actor and defaults to true.
          schema:
            type: boolean
            default: true
      responses:
        "200":
          description: "The subscriber"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscriber"
    delete:
      summary: "Delete a specific subscription from the subscriber."
      description: "Delete a specific subscription from the subscriber."
      tags:
        - subscriptions
      parameters:
        - name: subscriber_id
          in: path
          description: "The identifier of the subscriber"
          required: true
          schema:
            type: string
        - name: event_type
          in: path
          description: "The action event type."
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "The subscriber"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscriber"

  /subscriber/{subscriber_id}/handle:
    get:
      summary: "[WebSocket] Listen to registered events of given subscriber"
      description: |
        ## WebSocket Endpoint
        The client needs to send all the required headers for a ws connection
        and has to handle the websocket protocol.<br/>
        **Note this can not be tested from within swagger!**

        The connection to this endpoint will never be closed.
        All action events of the system this subscriber has registerd will be send to this
        connection.
      tags:
        - subscriptions
      parameters:
        - name: subscriber_id
          in: path
          description: "The identifier of the subscriber"
          required: true
          schema:
            type: string

      responses:
        "404":
          description: "No subscriber found"
          content:
            text/plain:
              schema:
                type: string
                example: No subscriber with this id
  # endregion

  # region task queue
  /work/queue:
    get:
      summary: "[WebSocket] Attach to the working queue"
      description: |
        ## WebSocket Endpoint
        The client needs to send all the required headers for a ws connection
        and has to handle the websocket protocol.<br/>
        **Note this can not be tested from within swagger!**

        This endpoint is used by worker nodes which can perform work.
        A worker would use this endpoint to establish a websocket connection and register the tasks
        that can be performed by the worker. One worker can perform one or more tasks over one connection.

        In case the connection is lost, all outstanding tasks are rescheduled to other workers.
        This means the local tasks queue should be wiped in case of connection loss.

        Note: the server tries to spread the number of tasks evenly over the number of workers.
        This number is derived by the number of outstanding messages in the queue irrelevant which tasks
        are outstanding.

      parameters:
        - name: task
          description: "The name of all tasks that this worker is able to perform."
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter
          description: |
            Additional properties to filter tasks of provided task name.
            The value of the parameter is either a string or a list of strings separated by comma.
            The available filter criteria are defined by the specific task to execute.

            All specified filter criteria need to match by the task to execute.
            If a list of values is defined for a filter criteria, at least one needs to match.
            (e.g. cloud=aws,gcp would match a task for cloud=aws).

            Example:
                     The worker is able to perform tasks of type tag, but only for cloud AWS:
                     cloud=aws

                     The worker is able to perform tasks of type tag, for AWS and GCP:
                     cloud=aws,gcp

                     Maybe the worker is only capable to perform the work in a specific account.
                     cloud=aws&account=123 could be specified to only filter for tasks in this cloud in this
                     account.

            In case there are multiple workers that match the task criteria, the most specific
            worker is taken.

            Example:
                    worker1: cloud=aws,gcp
                    worker2: cloud=aws account=123

            If the task is for cloud=aws and account=123, then only worker2 would get the task to execute
            not worker1.


          in: query
          required: false
          schema:
            type: object
            additionalProperties: true
            example: { "cloud": "aws", "account": "123,124,125" }
      tags:
        - work_queue
      responses:
        "200":
          description: When the connection is established.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
  /work/list:
    get:
      summary: "List all outstanding work items"
      description: |
        All work items that are initiated but not done are listed via this endpoint.
      tags:
        - work_queue
      responses:
        "200":
          description: The list of all outstanding work items
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    task:
                      type: object
                      properties:
                        task_id:
                          type: string
                        task_name:
                          type: string
                        data:
                          type: object
                          additionalProperties: true
                        attrs:
                          type: object
                          additionalProperties: true
                    worker:
                      type: string
                    retry_counter:
                      type: integer
                    deadline:
                      type: string

  # endregion

  # region config
  /configs:
    get:
      summary: "Get all configuration keys"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Get all configuration keys in the system.
      tags:
        - config
      responses:
        "200":
          description: All configuration keys.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /configs/model:
    get:
      summary: "Get the currently defined configuration model."
      tags:
        - config_validation
      responses:
        "200":
          description: "The list of all kinds."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kind"
    patch:
      summary: "Add or update the current defined configuration model."
      tags:
        - config_validation
      requestBody:
        description: "Complete model or part of the model."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Kind"
      responses:
        "200":
          description: "OK if the model is updated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Kind"
        "400":
          description: "Message that explains the error"
          content:
            text/plain:
              schema:
                type: string

  /configs/validation:
    get:
      summary: "Get all configuration keys that have a model defined."
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Get all configuration keys that have a model defined.
      tags:
        - config_validation
      responses:
        "200":
          description: All configuration keys that have a model.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /config/{config_id}:
    get:
      summary: "Get a configuration by its id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Fetch a configuration by id.
      tags:
        - config
      parameters:
        - name: config_id
          required: true
          in: path
          description: the identifier of the config to get.
          schema:
            type: string
      responses:
        "200":
          description: The configuration
          headers:
            Resoto-Config-Revision:
              description: The revision of this config
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "404":
          description: No configuration for this key.

    put:
      summary: "Replace a configuration with given id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Replace a configuration identified by id with provided value.
      tags:
        - config
      parameters:
        - name: config_id
          required: true
          in: path
          description: the identifier of the config to get.
          schema:
            type: string
        - name: validate
          required: false
          in: query
          description: |
            This parameter can be used to turn off config validation.
            In case it is not defined or not set to false, every configuaration value is validated.
          schema:
            type: boolean
        - name: dry_run
          required: false
          in: query
          description: |
            This parameter can be used to test if the config could be updated without really changing it.
            It will perform all validations but not store the new value.
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: The configuration
          headers:
            Resoto-Config-Revision:
              description: The revision of this config
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    patch:
      summary: "Patch a configuration by its id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Patch a configuration identified by id with provided value.
      tags:
        - config
      parameters:
        - name: config_id
          required: true
          in: path
          description: the identifier of the config to get.
          schema:
            type: string
        - name: validate
          required: false
          in: query
          description: |
            This parameter can be used to turn off config validation.
            In case it is not defined or not set to false, every configuaration value is validated.
          schema:
            type: boolean
        - name: dry_run
          required: false
          in: query
          description: |
            This parameter can be used to test if the config could be patched without really changing it.
            It will perform all validations but not store the new value.
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: The configuration
          headers:
            Resoto-Config-Revision:
              description: The revision of this config
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    delete:
      summary: "Delete a configuration by its id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Delete a configuration identified by id with provided value.
      tags:
        - config
      parameters:
        - name: config_id
          in: path
          required: true
          description: the identifier of the config to get.
          schema:
            type: string
      responses:
        "204":
          description: Signals success of this operation.

  /config/{config_id}/validation:
    get:
      summary: "Get a configuration validation by its id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Fetch the validation of a configuration by id.
      tags:
        - config_validation
      parameters:
        - name: config_id
          required: true
          in: path
          description: the identifier of the configuration validation.
          schema:
            type: string
      responses:
        "200":
          description: The configuration validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigValidation"
            application/yaml:
              schema:
                $ref: "#/components/schemas/ConfigValidation"
        "404":
          description: No config validation for this key.

    put:
      summary: "Replace a configuration validation with given id"
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Replace a configuration validation identified by id with provided value.
      tags:
        - config_validation
      parameters:
        - name: config_id
          required: true
          in: path
          description: the identifier of the configuration validation to replace.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfigValidation"
      responses:
        "200":
          description: The configuration validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigValidation"
  # endregion

  # region cli
  /cli/evaluate:
    post:
      summary: "Evaluate a cli command"
      description: |
        This method can be used to analyze if the command can be interpreted without executing it.
        When this method returns a 200 OK, the command can be parsed and evaluated.
      parameters:
        - name: env
          description: "All search parameter form the environment passed to the CLI interpreter."
          in: query
          schema:
            type: object
            additionalProperties: true
      requestBody:
        description: |
          The command will be sent as request body.
          A command can contain multiple command line separated by semicolon.
          Every single line can contain multiple commands that are combined via the pipe operator.
        content:
          text/plain:
            schema:
              type: string
              example: json [1,2,3,4,5,6] | count
      tags:
        - cli
      responses:
        "200":
          description: When the command can be evaluated.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        "300":
          description: When the command can not be evaluated.
          content:
            text/plain:
              schema:
                type: string

  /cli/execute:
    post:
      summary: "Execute a cli command"
      description: |
        The body defines the command to execute.
        The command is executed and the result is returned to the client.
        Request and execution are synchronized: the request is done, when the command is done.
      parameters:
        - name: env
          description: "All search parameter form the environment passed to the CLI interpreter."
          in: query
          schema:
            type: object
            additionalProperties: true
      requestBody:
        description: |
          The command will be sent as request body.
          A command can contain multiple command line separated by semicolon.
          Every single line can contain multiple commands that are combined via the pipe operator.
        content:
          text/plain:
            schema:
              type: string
              example: json [1,2,3,4,5,6] | count
      tags:
        - cli
      responses:
        "200":
          description: The result of the command.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
            application/x-ndjson:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
  /cli/info:
    get:
      summary: Get information about CLI
      description: |
        **Experimental**: This API is not stable and might be subject of change.<br/>
        Get information about CLI
      tags:
        - cli
      responses:
        "200":
          description: name, information and help of available commands.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CLIInfo"

  # endregion

  # region certificate
  /ca/cert:
    get:
      summary: Retrieve the certificate authorities public certificate.
      description: The certificate served here is only used to sign and validate.
      tags:
        - certificate
      responses:
        "200":
          description: "The certificate in PEM format."
          content:
            application/x-pem-file:
              schema:
                type: string
                example: |
                  -----BEGIN CERTIFICATE-----
                  MIIDUjCCAjqgAwIBAgIUEtDMkiSa2FYM5LVhZiPlspro39owDQYJKoZIhvcNAQEL
                  BQAweDELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcM
                  DVNhbiBGcmFuY2lzY28xHjAcBgNVBAoMFVNvbWUgRW5naW5lZXJpbmcgSW5jLjEc
                  MBoGA1UEAwwTQ2xvdWRrZWVwZXIgUm9vdCBDQTAeFw0yMTEyMjIwOTQ1NDJaFw0y
                  MjEyMjIwOTQ1NDJaMBsxGTAXBgNVBAMMEHNvbWUuZW5naW5lZXJpbmcwggEiMA0G
                  CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5VIgOTR95jIxWJZHXUo6FUv4CyDn/
                  fZWxZQmFXC8c6SqspRNpXMgZq+riTm+yQ1l/kc2xVpr5S8tVeFGGjzaCcf51DMSx
                  j7SaUXP2oDtMi7e9wkfTaoN3z3erVwJl39znKQviEL8G7vYPCn7oDqt1HHry7ctN
                  crEMWYSQXUYe4s++K1q65VyGNBp6AcIrmefoH0pGARZs4MbvR74U44xsj25VFS+W
                  M3YSomBv4oB4QkqlcVWOU/Tlx7Tq7ASfkSqEkUigKMx/QKrdeQHxCkEtmjbiHhOk
                  VaCYsVbi8pVvE5URNrycvzJXGdimSL8pVZ8M89gUDoxUoiAneSswoRZrAgMBAAGj
                  MTAvMA4GA1UdDwEB/wQEAwIFoDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
                  AwIwDQYJKoZIhvcNAQELBQADggEBAA70yqOYfYtguJKji+IeIsZflNH2DH6lZ2Xe
                  mv5suRbjuKEApSDUL59rpliT1dAcX6+cfKDQjzZ/7VWmp+XZmehGRlhRNWJMzsOz
                  Xv8/5l0LL59yN4w4FNq2cREcLj35RVYUU7lssNr/RNE9xNMHeqLdC4oW22PUi1lY
                  iq212G5yQTg31lVmzA9Uzvz+p/A8CG24tSBFbydSIogprmALS+5rnso0bWJ3Owf1
                  CVz6Dc9UM4kBWDsb+iTffXwbgSDbG+lJ+9TEndcAzb7Zxs6ghMtv/PKR/tmw+O32
                  3da9fAZE2eZoDvssH6LAUcFjtP9SFb8ZOdHJ15l279vzgCvWsvU=
                  -----END CERTIFICATE-----
  /ca/sign:
    post:
      summary: Sign a certificate request.
      tags:
        - certificate
      requestBody:
        description: The certificate signing request (csr) in pkcs10 format.
        content:
          application/pkcs10:
            schema:
              type: string
              example: |
                -----BEGIN CERTIFICATE REQUEST-----
                MIICYDCCAUgCAQAwGzEZMBcGA1UEAwwQc29tZS5lbmdpbmVlcmluZzCCASIwDQYJ
                KoZIhvcNAQEBBQADggEPADCCAQoCggEBAM6QVB0C0G1yJRD1aWye8a1IscJa4cN4
                +PDWim+2qemCRpiIafgsict5AtlqmvDaYYs7uaLI8PLASMz0pnrxLaVbRVu5H7Ix
                KSh1Vz/WjsqTDNw5Q+qPpT/YPP5l02IrKrP/pdMNC0FYnDxr6Y4bXVuFqtMv+Zr2
                amJSIpOET2wswo6MRflfiO9jh8mD5mdU+SqDHAvBpU7H3L4rd3cWyVsz3Q4cqpwa
                SDayhRMewxusI2MTj/uNEzZYTWiHb2TXUkYYSMYazdbVRUKFNWOsq+z1RPV1IUUe
                g0yjNS+tfYF0numPzwt9GNuB18O3X1G5rs2nHDRQL8pAbcy5Wjsuwf0CAwEAAaAA
                MA0GCSqGSIb3DQEBCwUAA4IBAQAuI5ijV9ahWtRhondwOYuYFMZL+i+tXPdn+O/B
                V7WFVdbaV13TpJ3giJBhCY3mlQ+Vb7BNDhgqdcsiXr4M1fDC0gf8J/GYA2s4yvrf
                fCqnFA97UET0AwpIA22+JZnZVs+FXqDsU2VMBgmGToU0QgzBSVi8/exSx3CWBgAk
                x2q98/r/Dhbi2KQkOYJ7yQx1t0416UiFB9xUnDIreg0k5chP5NF1YRbsatParYhG
                OviEEbELaTnWbmfnveBWjxAImv5w3tkF/dapH+QQ5yTIzDEl/UoG2pXC6QGRaRsp
                Mft1XSBtZDykb6SrTTz/lUfjn3XX+zqQ7g466HvglAwqUfX1
                -----END CERTIFICATE REQUEST-----
      responses:
        "200":
          description: "The certificate in PEM format."
          content:
            application/x-pem-file:
              schema:
                type: string
                example: |
                  -----BEGIN CERTIFICATE-----
                  MIIDUjCCAjqgAwIBAgIUEtDMkiSa2FYM5LVhZiPlspro39owDQYJKoZIhvcNAQEL
                  BQAweDELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcM
                  DVNhbiBGcmFuY2lzY28xHjAcBgNVBAoMFVNvbWUgRW5naW5lZXJpbmcgSW5jLjEc
                  MBoGA1UEAwwTQ2xvdWRrZWVwZXIgUm9vdCBDQTAeFw0yMTEyMjIwOTQ1NDJaFw0y
                  MjEyMjIwOTQ1NDJaMBsxGTAXBgNVBAMMEHNvbWUuZW5naW5lZXJpbmcwggEiMA0G
                  CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5VIgOTR95jIxWJZHXUo6FUv4CyDn/
                  fZWxZQmFXC8c6SqspRNpXMgZq+riTm+yQ1l/kc2xVpr5S8tVeFGGjzaCcf51DMSx
                  j7SaUXP2oDtMi7e9wkfTaoN3z3erVwJl39znKQviEL8G7vYPCn7oDqt1HHry7ctN
                  crEMWYSQXUYe4s++K1q65VyGNBp6AcIrmefoH0pGARZs4MbvR74U44xsj25VFS+W
                  M3YSomBv4oB4QkqlcVWOU/Tlx7Tq7ASfkSqEkUigKMx/QKrdeQHxCkEtmjbiHhOk
                  VaCYsVbi8pVvE5URNrycvzJXGdimSL8pVZ8M89gUDoxUoiAneSswoRZrAgMBAAGj
                  MTAvMA4GA1UdDwEB/wQEAwIFoDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
                  AwIwDQYJKoZIhvcNAQELBQADggEBAA70yqOYfYtguJKji+IeIsZflNH2DH6lZ2Xe
                  mv5suRbjuKEApSDUL59rpliT1dAcX6+cfKDQjzZ/7VWmp+XZmehGRlhRNWJMzsOz
                  Xv8/5l0LL59yN4w4FNq2cREcLj35RVYUU7lssNr/RNE9xNMHeqLdC4oW22PUi1lY
                  iq212G5yQTg31lVmzA9Uzvz+p/A8CG24tSBFbydSIogprmALS+5rnso0bWJ3Owf1
                  CVz6Dc9UM4kBWDsb+iTffXwbgSDbG+lJ+9TEndcAzb7Zxs6ghMtv/PKR/tmw+O32
                  3da9fAZE2eZoDvssH6LAUcFjtP9SFb8ZOdHJ15l279vzgCvWsvU=
                  -----END CERTIFICATE-----
  # endregion

  # region system
  /system/ready:
    get:
      summary: This endpoint signals if the system is ready to serve traffic.
      tags:
        - system
      responses:
        "200":
          description: "This response code signals, that the system is ready."
          content:
            text/plain:
              schema:
                type: string
                example: "200: OK"
  /system/ping:
    get:
      summary: Send a ping to the system and expect a pong.
      tags:
        - system
      responses:
        "200":
          description: "The pong answer"
          content:
            text/plain:
              schema:
                type: string
                example: pong

  # endregion
components:
  schemas:
    AnalyticsEvent:
      description: "An analytics event."
      type: object
      properties:
        system:
          type: string
          description: The system that emitted the event.
        kind:
          type: string
          description: The kind of event.
        context:
          type: object
          description: The context of the event.
          additionalProperties:
            type: string
        counters:
          type: object
          description: The counters of the event.
          additionalProperties:
            type: integer
        at:
          type: string
          description: The time of the event in IS0 8601 date time.
    Config:
      description: "A config object"
      type: object
      properties:
        id:
          type: string
          description: The id of this config object.
        config:
          type: object
          additionalProperties: true
    Subscriber:
      description: "A subscriber has a unique name and a list of subscriptions"
      type: object
      properties:
        id:
          type: string
          description: "The identifier of this subscriber"
        subscriptions:
          type: object
          description: "The dictionary of subscriptions, where the key is the message type"
          additionalProperties:
            $ref: "#/components/schemas/Subscription"
    Subscription:
      description: "The definition of an action subscription"
      type: object
      properties:
        message_type:
          type: string
          description: "The name of the action to listen to"
        wait_for_completion:
          type: boolean
          description: |
            If an action is sent to this subscriber, the event sender should wait until this
            subscriber has processed the message and send a done message.
            This is the expected behaviour of every actor and defaults to true.
          default: true
        timeout:
          type: number
          description: |
            This is the duration in seconds this subscriber has time to execute the action.
            After this time the sender assumes a failure and rejects the result of this actor.
          default: 60
    Aggregated:
      description: "The result of the aggregation. The properties depend on the aggregation function."
      type: object
      additionalProperties: true
      example: |
        [
            { "count": 60, "kind": "aws_ec2_instance_type", "mem_avg": 28.45, "mem_max": 64, "mem_min": 1, "mem_total": 1707 },
            { "count": 105686, "kind": "gcp_machine_type", "mem_avg": 213.57744392143945, "mem_max": 3844, "mem_min": 0.599609375, "mem_total": 22572145.73828125 }
        ]
    BatchUpdate:
      type: object
      properties:
        id:
          type: string
          description: "the id of the change."
        created:
          type: string
          description: "datetime in utc, when the batch update has been created"
        affected_nodes:
          type: array
          items:
            type: string
          description: "The root nodes of the subgraphs that will be changed during the update"
      example:
        [
          {
            "id": "XYQaijCNJUVc",
            "created": "2021-06-29T13:53:39.329Z",
            "affected_nodes": [ "sub_graph_root_1", "sub_graph_root_2" ]
          }
        ]
    Node:
      type: object
      additionalProperties: true
      properties:
        kind:
          type: string
          description: "The kind of this node."
      example:
        {
          "kind": "test.person",
          "name": "Batman",
          "city": "Gotham"
        }
    NodeInGraph:
      type: object
      properties:
        id:
          type: string
          description: "The identifier of this node."
        type:
          type: string
        reported:
          $ref: "#/components/schemas/Node"
        desired:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
      example:
        {
          "type": "node",
          "id": "id-in-graph",
          "reported": {
            "kind": "test.person",
            "name": "Batman",
            "city": "Gotham"
          },
          "desired": {
            "clean": true
          },
          "metadata": {
            "version": 1
          }

        }
    DesiredNode:
      type: object
      properties:
        reported:
          $ref: "#/components/schemas/Node"
        desired:
          type: object
          description: "The desired section does not contain a complete node, but only the desired changes."
          additionalProperties: true
      example:
        {
          "reported": {
            "kind": "test.person",
            "name": "Batman",
            "city": "Gotham"
          },
          "desired": {
            "name": "Superman"
          }
        }
    Edge:
      type: object
      properties:
        from:
          description: "The id of node to start from"
          type: string
        to:
          description: "The id of the node to go to"
          type: string
        edge_type:
          description: "The type of this edge"
          type: string
          enum:
            - default
            - delete
      example:
        {
          "type": "edge",
          "from": "node_id_of_a_in_graph",
          "to": "node_id_of_b_in_graph",
          "edge_type": "default"
        }
    Graph:
      description: "A graph is just an array of nodes and edges"
      type: array
      items:
        discriminator:
          propertyName: "type"
          mapping:
            "node": "#/components/schemas/NodeInGraph"
            "edge": "#/components/schemas/Edge"
        oneOf:
          - $ref: "#/components/schemas/NodeInGraph"
          - $ref: "#/components/schemas/Edge"
    GraphUpdate:
      description: "Summary of a graph change action"
      type: object
      properties:
        nodes_created:
          description: "The number of nodes that have been created."
          type: integer
        nodes_updates:
          description: "The number of nodes that have been updated."
          type: integer
        nodes_deleted:
          description: "The number of nodes that have been deleted."
          type: integer
        edges_created:
          description: "The number of edges that have been created."
          type: integer
        edges_updated:
          description: "The number of edges that have been updated."
          type: integer
        edges_deleted:
          description: "The number of edges that have been deleted."
          type: integer
    ConfigValidation:
      description: "The validation for this configuration value."
      type: object
      properties:
        id:
          description: The identifier of the related configuration.
          type: string
        external_validation:
          description: |
            True, if an external entity should validate a config change.
            In this case resotocore is emitting a task on the task queue of type validate_config.
            It expectes a listener to pickup this task and report back, if the configuration is valid or not.
          type: boolean
    Kind:
      description: "Definition of a kind"
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/StringKind'
          - $ref: '#/components/schemas/NumberKind'
          - $ref: '#/components/schemas/BooleanKind'
          - $ref: '#/components/schemas/DateTimeKind'
          - $ref: '#/components/schemas/ArrayKind'
          - $ref: '#/components/schemas/DateKind'
          - $ref: '#/components/schemas/ComplexKind'
          - $ref: '#/components/schemas/StringDictKind'
      example:
        [
          {
            "fqn": "test.dice",
            "runtime_kind": "int32",
            "description": "A dice has 6 sides.",
            "minimum": 1,
            "maximum": 6
          },
          {
            "fqn": "test.social_security_number",
            "runtime_kind": "string",
            "description": "A dice has 6 sides.",
            "pattern": "^(?!666|000|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0{4})\\d{4}$"
          },
          {
            "fqn": "test.base",
            "properties": [
              {
                "name": "kind",
                "kind": "string",
                "required": true,
                "description": "The kind of this compound type."
              },
              {
                "name": "name",
                "kind": "string",
                "description": "The name of the resource.",
                "required": true
              },
              {
                "name": "tags",
                "kind": "dictionary[string, string]",
                "description": "Tags that describe the resource.",
                "required": false
              }
            ]
          },
          {
            "fqn": "test.person",
            "bases": [ "test.base" ],
            "properties": [
              {
                "name": "fortune",
                "kind": "test.dice",
                "description": "The current dice value.",
                "required": true
              },
              {
                "name": "ssn",
                "kind": "test.social_security_number",
                "description": "The social security number of this person.",
                "required": true
              }
            ]
          }
        ]
    KindBase:
      type: object
      properties:
        fqn:
          type: string
          description: "The fully qualified name of the kind"
    SimpleKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/KindBase'
      discriminator:
        propertyName: runtime_kind
        mapping:
          string: "#/components/schemas/StringKind"
          int32: "#/components/schemas/NumberKind"
          int64: "#/components/schemas/NumberKind"
          float: "#/components/schemas/NumberKind"
          double: "#/components/schemas/NumberKind"
          boolean: "#/components/schemas/BooleanKind"
          date: "#/components/schemas/DateKind"
          datetime: "#/components/schemas/DateTimeKind"

      properties:
        runtime_kind:
          type: string
          enum:
            - string
            - int32
            - int64
            - float
            - double
            - boolean
            - date
            - datetime
          description: "The runtime kind of this kind"
    StringKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/SimpleKind'
      properties:
        min_length:
          type: string
          description: "The minimal length of this string"
        max_length:
          type: string
          description: "The maximal length of this string"
        pattern:
          type: string
          description: "The regexp pattern, that this string has to adhere to"
        enum:
          type: array
          items:
            type: string
          description: "The allowed values of this string enumerated here"
    NumberKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/SimpleKind'
      properties:
        minimum:
          oneOf:
            - type: integer
            - type: number
          description: "The minimal value of this number"
        maximum:
          oneOf:
            - type: integer
            - type: number
          description: "The maximum value of this number"
        enum:
          type: array
          items:
            type: integer
          description: "The allowed values of this number enumerated here"
    BooleanKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/SimpleKind'
    DateTimeKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/SimpleKind'
    DateKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/SimpleKind'
    ArrayKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/KindBase'
      properties:
        inner:
          $ref: "#/components/schemas/KindBase"
    Property:
      type: object
      properties:
        name:
          type: string
          description: "The name of this property"
        kind:
          type: string
          description: "The fully qualified kind of this property"
        required:
          type: boolean
          description: "Defines if this property is required or not"
          default: false
        description:
          type: string
          description: "Some human readable description of this property"
    ComplexKind:
      type: object
      allOf:
        - $ref: '#/components/schemas/KindBase'
      properties:
        bases:
          type: array
          items:
            type: string
          description: "In case of inheritance, this defines the base kinds."
        properties:
          type: array
          description: "Defines all properties of this complex kind"
          items:
            $ref: '#/components/schemas/Property'
        allow_unknown_props:
          type: boolean
          default: False
          description: "In case properties are accepted, that are not listed in the model"
        successor_kinds:
          description: "Dictionary of successor kinds."
          example: |
            { "default": ["kind1", "kind2"], "delete": ["kind3"] }
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    StringDictKind:
      type: object
      description: "A simple dictionary where all keys and values are strings"
      allOf:
        - $ref: '#/components/schemas/KindBase'

    RawQuery:
      type: object
      description: "The raw query as performed by the database"
      properties:
        query:
          type: string
          description: "The string representation of the query"
        bind_vars:
          type: object
          description: "All binding variables for this query"
          additionalProperties: true

    EstimatedSearchCost:
      type: object
      description: "The estimated cost of a search"
      properties:
        estimated_cost:
          type: integer
          description: Absolute number that shows the cost of this search. See rating for an interpreted number.
        estimated_nr_items:
          type: integer
          description: |
            This is the estimated number of items returned for this search.
            Please note: it is computed based on search statistics and heuristics and does not reflect the real number.
        available_nr_items:
          type: integer
          description: This is the number of available nodes in the graph.
        full_collection_scan:
          type: boolean
          description: |
            Indicates, if a full collection scan is required.
            This means, that the search does not take advantage of any indexes!
        rating:
          type: string
          description: |
            The rating of this search.
            A simple search is usually fine.
            A complex search might be acceptable in certain cases. Maybe an index can be used to make this search simple?
            A bad search is usually something where an index is missing or the search has to be rewritten.
          enum:
            - simple
            - complex
            - bad

    CLIInfo:
      type: object
      description: Information about the CLI
      properties:
        commands:
          description: All available commands
          type: array
          items:
            $ref: '#/components/schemas/CLICommand'
        replacements:
          description: All available replacements with current value
          type: object
          additionalProperties:
            type: string
        alias_names:
          description: All available aliases
          type: object
          additionalProperties:
            type: string
        alias_templates:
          description: All available alias template name.
          type: array
          items:
            $ref: '#/components/schemas/CLICommand'
    CLICommand:
      type: object
      description: Information about a CLI command
      properties:
        name:
          type: string
          description: The name of the CLI command.
        args:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/CLICommandArg'
            - $ref: '#/components/schemas/CLICommandArg'
        info:
          type: string
          description: Short description.
        help:
          type: string
          description: Help text of the CLI command.
        source:
          type: boolean
          description: Indicates, if the command is allowed in source position (first command in a chain).

    CLICommandArg:
      type: object
      properties:
        name:
          type: string
          description: The name of the CLI command argument.
        expects_value:
          type: boolean
          description: Indicates, if the argument expects a value.
        possible_values:
          type: array
          items:
            type: string
          description: Possible values for this argument.
        can_occur_multiple_times:
          type: boolean
          description: Indicates, if the argument can occur multiple times.
        value_hint:
          type: string
          description: Hint for the value of this argument.
        help_text:
          type: string
          description: Help text of the CLI command argument.