API
      Back to home
      1. Hyperglance Support
      2. Setup & Configuration
      3. API

      Hyperglance Inventory API Reference

      Technical Reference

      Table of Contents

       

      Getting Started

      The Hyperglance API is exposed on: https://<host>/hgapi
      All paths in this document are relative to that root URL.

      To use this API you must generate an API key and use it to authenticate by passing it as an HTTP Authorization header (for details see Authentication).

      Concepts & Terminology

      Datasource A datasource is a unique name assigned to an HGAPI application and so serves to identify the source of topology data in Hyperglance (e.g. Amazon, Azure, Kubernetes).
      Your HGAPI application has a single datasource name. You will usually want to hard-code this into your application.
      Examples: "AcmeApp", “OpenStack”, "John's MongoDb"
      Topology A topology is a well-formed piece of the overall Network and could be a single AWS Account, Azure Subscription or Kubernetes cluster.
      Groups

      A kind of entity that appears in the Hyperglance diagram as a box with an icon that can contain nested parts of the topology.
      Examples: Regions, Subnets
      Nodes A kind of entity often used to model network devices or top-level concepts.
      Examples: Load-Balancers, NAT Gateways
      Endpoints A kind of entity often used to model network interface or other hardware elements.
      An endpoint maybe be attached to a Node or a Group.
      Examples: Network Interface Cards, Ports, Logical Disk Partitions.
      Links A kind of entity often used to model connectivity or relationships between groups, nodes and endpoints and always spans between two points in the diagram.

      Examples: Routing links, links between VM and Loadbalancers
      Alarms A kind of entity often used to model alarms/alerts/problems.
      An alarm always belongs to either a node or an endpoint.
      Examples: High CPU Alarm, Service Down Alarm.
      Attributes Textual key/value data. All nodes, endpoints and links support attributes.
      Types Every kind of entity (Node, Endpoint, Link, Group, etc) has a type.
      A type can be any string and is used to indicate the user about the particular ‘type’ of Node (or Endpoint/Link/Group/Alarm) that they are looking at.
      Examples: vm, host, switch, router, connection
      Keys A type of local ID used by Hyperglance which often matches with the original cloud resource's identifier (e.g. an instance-id).
      Unique IDs
      (UIDs)      		 An ID built by Hyperglance for every entity in the inventory and is completely unique within the entire inventory.
      The format and structure of UID strings is undefined and subject to change. Do not depend on it.



      APIs

      All paths are specified relative to the HGAPI’s root endpoint URL, see “Getting Started” section.

      Network API

      GET /network

      Returns the inventory graph of Hyperglance inluding all groups, nodes, links and so on.

      Normal response codes: 200 OK
      Error response codes:       400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

      Example response:

      {
      "updatedAt": 123456789,
      "topologies": [
      {
      "name": "example topology",
      "datasource": "AcmeApp",
      "nodes": [
      {
      "UID": "902c-8ce241a85bbb",
      "key": "node1",
      "name": "new-vm-test",
      "type": "vm",
      "attributes": [
      { "name": "Company", "value": "Acme Corp." }
      ],
      "groupKey": "g1"
      },
      {
      "UID": "9421-8bb2a8139669",
      "key": "node2",
      "name": "lab host1",
      "type": "host",
      "attributes": [
      { "name": "Company", "value": "Acme Corp." }
      ],
      "groupKey": "g1"
      }
      ],
      "endpoints": [
      {
      "UID": "8c73-e7f06f359a1f",
      "key": "ep1",
      "name": "ep1",
      "type": "virtual port",
      "attributes": [],
      "ownerUID": "902c-8ce241a85bbb"
      },
      {
      "UID": "988a-60aa3b19f13a",
      "key": "ep2",
      "name": "ep2",
      "type": "physical port",
      "attributes": [],
      "ownerUID": "9421-8bb2a8139669"
      }
      ],
      "links": [
      {
      "UID": "becd-5c6d4c62b09c",
      "key": "link1",
      "name": "link1",
      "type": "virtual<->physical connection",
      "attributes": [],
      "nodeAUID": "902c-8ce241a85bbb",
      "nodeBUID": "9421-8bb2a8139669",
      "endpointAUID": "8c73-e7f06f359a1f",
      "endpointBUID": "988a-60aa3b19f13a"
      }
      ],
      "alarms": [
      {
      "UID": "898e-87ef7fed4dff",
      "key": "alarm1",
      "name": "High CPU",
      "type": "metric alarm",
      "attributes": [
      {
      "name": "Description",
      "value": "CPU exceeded threshold!"
      }
      ],
      "ownerUID": "902c-8ce241a85bbb",
      "severity": "CRITICAL"
      }
      ],
      "groups": [
      {
      "UID": "AcmeApp|example topology|GROUP|VPC|g1",
      "key": "g1",
      "type": "VPC",
      "name": "group1",
      "appTags": [],
      "attributes": [
      {
      "name": "Description",
      "value": "Small subset of Topology"
      }
      ],
      "dependsOnNodeKeys": [],
      "urls": [],
      "parentGroupKey": null
      }
      ]
      }
      ]
      }

      JSON elements:

      updatedAt Integer Time the Network was last updated.
      Unit: Seconds since Unix Epoch.
      topologies List of Topologies All topologies contributed by a data-source.
      Absent from these topologies are any non-creatable entities.
      datasource String The data-source identifier.
      name String Name of topology (e.g. account or subscription alias)
      nodes List of Nodes Nodes in a topology.
      endpoints List of Endpoints Endpoints in a topology.
      links List of Links Links in a topology.
      alarms List of Alarms Alarms in a topology.
      groups  List of groups Groups in a topology.
      UID UID String The UID of the Node, Endpoint, Link or Alarm.
      key String The Key of the Node, Endpoint, Link or Alarm.
      type String The Type of the Node, Endpoint, Link or Alarm.
      groupKey  String The group name of the node.
      parentGroupKey String The group name of the child group.
      name String The name of a Node, Endpoint, Link or Alarm.
      attributes List of Attributes Attributes of the Node, Endpoint, Link, Alarm or Group.
      name String The name of an Attribute.
      value String The value of an Attribute.
      ownerUID UID String The UID of the Node/Group that an Endpoint attaches to.
      nodeAUID UID String The UID of a Node that a Link attaches to.
      nodeBUID UID String The UID of a Node that a Link attaches to.
      endpointAUID (optional) UID String The UID of an Endpoint that a Link attaches to.
      endpointBUID (optional) UID String The UID of an Endpoint that a Link attaches to.
      ownerUID UID String The UID of a Node or Endpoint that an Alarm attaches to.
      severity String The severity of an Alarm.
      One of: CRITICAL, SEVERE, WARNING, INFO.

       

      Example Scripts:


      Augmentation API

      PUT /augment

      Allows for attach custom attributes, custom hyperlinks and custom apptags (for tag-views) onto resource items in Hyperglance. You will be able to see your attributes, hyperlinks and tag-views in the Hyperglance UI.

      Normal response codes: 200 OK, 202 Accepted
      Error response codes:       400 Bad Request, 401 Unauthorized, 403 Forbidden

       

      Example request:

      {
      "appTags": [
      {
      "UID": "acda-dee6d506a1db",
      "appTags": ["AugmentedAppTag1", "AugmentedAppTag2"]
      }
      ],
      "attributes": [
      {
      "UID": "acda-dee6d506a1db",
      "attributes": [
      { "name": "Contact E-Mail", "value": "jon@example.com" }
      ]
      }
      ],
      "urls":[
      {
      "UID": "acda-dee6d506a1db",
      "urls":[
      {
      "displayName":"Hyperglance",
      "urlPath":"https://twitter.com/hyperglance"
      }
      ]
      }
      ]
      }

      JSON elements:

      attributes List of Attribute-Augmentations Attribute-Augmentations to apply.
      Any Attribute-Augmentations created prior by this API Key will be replaced.
      urls List of URL-Augmentations URL-Augmentations to apply.
      Any URL-Augmentations created prior by this API Key will be replaced.
      appTags List of AppTag-Augmentations AppTag-Augmentations to apply.
      Any Attribute-Augmentations created prior by this API Key will be replaced.
      UID UID String The UID of a Node, Endpoint, Link, Alarm or Group receiving the augmentation.
      attributes List of Attributes Attribute Key and Value pairs to attach to the intended resource.
      urls List of URLs Hyperlinks to attach to the intended resource.
      appTags List of Strings App Tag names to attach to the intended resource.
      name String The name of an attribute.
      value String The value of an attribute.
      displayName String The hyperlink text that will be shown in the Hyperglance UI.
      urlPath String The hyperlink URL.

       

      Example Scripts: