Hyperglance REST API (HGAPI)

Technical Reference

Version 5.2

April 2018





Table of Contents

Hyperglance REST API (HGAPI). 1

Getting Started. 3

Overview.. 3

Concepts & Terminology. 3

Authentication. 5

HGAPI v3.0. 6

Network API - Get Network. 6

Topology API - List. 10

Topology API - Create/Update. 13

Topology API - Remove. 18

Augmentation API - Attributes. 19

Augmentation API – Application Tags. 20

Augmentation API – Depends On. 20

Augmentation API – Entity Specific Urls. 21

Python Code Samples. 23

Running the Samples. 23



Getting Started

Overview

The Hyperglance API (HGAPI) is a RESTful JSON web service API to support integrations with 3rd party applications; HGAPI client applications can create new topology or overlay additional data onto existing topology. They can also retrieve data out from the Hyperglance platform.

The HGAPI is exposed by the Hyperglance Server (HGS). The API's root endpoint is located at: https://<host>/hgapi

Note: We strongly recommend that client applications be configurable, in case this endpoint URL is ever changed in future versions of Hyperglance, or by administrators.

Developers should be aware when parsing responses from the HGAPI that these responses may contain extra additional JSON fields compared to those documented. Therefore HGAPI clients should be prepared to simply ignore any extra undocumented fields.

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.
An HGAPI application has a single datasource name. Typically the name is chosen based on the underlying system from which data is retrieved. 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.
Every client application contributes at least one topology. Multiple topologies can be added/updated/removed by HGAPI client applications. The use of multiple topologies by a single client application is supported purely for organizational purposes.
A topology is a graph structure consisting of Groups, Nodes, Endpoints and Links. Each of which can have Attributes.
Network
An aggregation of all topologies which occurs periodically within the HGS.
Nodes
A kind of entity often used to model network devices or top-level concepts.
Examples: Servers, Virtual-Machines, Load-Balancers.
Endpoints
A kind of entity often used to model hardware components or second-level concepts.
An endpoint always belong to a node. A node can own many endpoints.
Examples: Network Interface Cards, Ports, Logical Disk Partitions.
Links
A kind of entity often used to model connectivity or relationships between nodes and endpoints.
A link always spans between two nodes, optionally it may connect to those nodes via endpoints.

Examples: SNMP Connectivity, Logical relationships.
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.
The Hyperglance Client uses type to assign icons as described here: https://support.hyperglance.com/solution/articles/11000044335-how-to-set-icons-for-nodes
Examples: vm, host, switch, router, connection, flow
Keys
An ID provided by the client application for every entity and must be unique within the context of a single topology.
Used to assign relationships between entities within a topology (e.g. Endpoints assigned to a node) and to track the lifetime of entities across updates to the topology.
Keys should be 'stable', meaning the same logical entity should be given the same key across updates to the topology.
Unique IDs
(UIDs)
An ID generated by the HGS for every entity and is completely unique within the entire network.
The format and structure of UID strings is undefined.
Collector-plugin
Closed-source Hyperglance Server plugins developed by Real-Status that also integrate with 3rd party applications rather like an HGAPI client application.

Authentication

Developers must generate an API Key for their application to use for authenticating with the HGS. Please remember that this API Key should be kept secret & secure and treated like a password. Every HGAPI client application should be given its own, unique API Key.

API Keys can be created and managed by visiting the 'API' section’s 'Register App' in the  Hyperglance admin panel https://IP_address/#/admin.

The HGAPI uses Basic-Access-Authentication with HTTPS for secure access. This protocol requires passing an “Authorization” header which encodes the unique Datasource and API Key as the username and password respectively.

Many web request tools & frameworks have a simple way to generate this “Authorization” header given the username and password. However the header can also be manually constructed as follows:

  • Combine the Datasource and API Key into a single string, separated by a colon: “Datasource:APIKey”
  • Encode this string into Base64 according to the RFC-2045 specification for MIME encoding and without any line length limit.
  • Prefix the encoded string with the word Basic and a space: “Basic “
  • Supply this string as the request header named “Authorization”.

For example if the Datasource is “AcmeApp” and the API Key is “a15f3a32-77f3-4784-b10c-ff8b0587495b” then the header will be:

Authorization
Basic QWNtZUFwcDphMTVmM2EzMi03N2YzLTQ3ODQtYjEwYy1mZjhiMDU4NzQ5NWI=

The authorization header must be provided in every API call made to the HGAPI.

Sample code:

  • examples/basic examples/rest_utils.py

HGAPI v3.0

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

Network API - Get Network

GET /network

Returns topologies from all datasources that have been aggregated into a coherent network that the Hyperglance Client could display. Topologies are grouped by datasource and can be filtered to a given datasource if the optional query parameter is provided.

Note: Due to the aggregation process, the topologies returned by this call may have been altered since they were originally contributed.

Note: The aggregation process is an automatic, periodic process so this call may not immediately reflect changes to a topology.

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

Query parameters:

datasource (optional)
The unique name identifier of a data-source to constrain the response to. Only the part of the network contributed by the provided data-source will be returned.

Example response:

{
    "updatedAt": 123456789,
    "network": [
        {
            "datasource": "AcmeApp",
            "topologies": [
                {
                    "name": "example topology"
                    "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": [],
                            "nodeUID": "902c-8ce241a85bbb"
                        },
                        {
                            "UID": "988a-60aa3b19f13a",
                            "key": "ep2",
                            "name": "ep2",
                            "type": "physical port",
                            "attributes": [],
                            "nodeUID": "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.
network
List of Datasource-Topologies
Topologies grouped by their data-source identifier.
datasource
String
The data-source identifier.
topologies
List of Topologies
All topologies contributed by a data-source.
Absent from these topologies are any non-creatable entities.
name
String
Name of topology.
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.
nodeUID
UID String
The UID of the Node 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.

Sample code:

  • examples/basic examples/get_network.py
  • examples/basic examples/augment_attributes2.py

 

Topology API - List

GET /topology

Lists all topologies as contributed by the HGAPI client application.

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

 

Example response:

{
    "topologies": [
        {
            "name": "example topology"
            "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": [],
                    "nodeKey": "node1",
                    "nodeUID": "902c-8ce241a85bbb"
                },
                {
                    "UID": "988a-60aa3b19f13a",
                    "key": "ep2",
                    "name": "ep2",
                    "type": "physical port",
                    "attributes": [],
                    "nodeKey": "node2",
                    "nodeUID": "9421-8bb2a8139669"
                }
            ],
            "links": [
                {
                    "UID": "becd-5c6d4c62b09c",
                    "key": "link1",
                    "name": "link1",
                    "type": "virtual<->physical connection",
                    "attributes": [],
                    "endpointAKey": "ep1",
                    "endpointAUID": "8c73-e7f06f359a1f",
                    "endpointBKey": "ep2",
                    "endpointBUID": "988a-60aa3b19f13a",
                    "nodeAUID": null,
                    "nodeBUID": null
                }
            ],
            "alarms": [
                {
                    "UID": "898e-87ef7fed4dff",
                    "key": "alarm1",
                    "name": "High CPU",
                    "type": "metric alarm",
                    "attributes": [
                        {
                            "name": "Description",
                            "value": "CPU exceeded threshold!"
                        }
                    ],
                    "nodeKey": "node1",
                    "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:

topologies
List of Topologies
All topologies contributed by this datasource.
name
String
Name of topology.
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 (optional)
UID String
The UID of the Node, Endpoint, Link or Alarm.
Will be null if the entity is not creatable:
E.g. An Endpoint is not creatable if its nodeKey or nodeUID are invalid.
key
String
The Key of the Node, Endpoint, Link or Alarm.
name
String
The name of a 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.
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.
nodeKey (optional)
String
The Key of the Node that an Endpoint or Alarm attaches to.
Will be null if one was not specified.
nodeUID
UID String
The UID of the Node that an Endpoint attaches to.
nodeAKey (optional)
String
The Key of a Node that a Link attaches to.
Will be null if one was not specified.
nodeAUID (optional)
UID String
The UID of a Node that a Link attaches to.
Will be null if an endpointAUID was specified instead.
nodeBKey (optional)
String
The Key of a Node that a Link attaches to.
Will be null if one was not specified.
nodeBUID (optional)
UID String
The UID of a Node that a Link attaches to.
Will be null if an endpointBUID was specified instead.
endpointAKey (optional)
String
The Key of an Endpoint that a Link attaches to.
Will be null if one was not specified.
endpointAUID (optional)
UID String
The UID of an Endpoint that a Link attaches to.
Will be null if a nodeAUID was specified instead.
endpointBKey (optional)
String
The Key of an Endpoint that a Link attaches to.
Will be null if one was not specified.
endpointBUID (optional)
UID String
The UID of an Endpoint that a Link attaches to.
Will be null if a nodeBUID was specified instead.
endpointKey (optional)
String
The Key of the Endpoint than an Alarm 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.

Sample code:

  • examples/basic examples/list_topologies.py

Topology API - Create/Update

PUT /topology

Creates or updates (if already created by the HGAPI client application) a single topology.

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

 

Example request:

{
    "name":"example topology",
    "nodes":[
        {
            "key":"node1",
            "name":"new-vm-test",
            "type":"vm",
            "groupKey": "g1",
            "attributes":[
                {
                    "name":"Company",
                    "value":"Acme Corp."
                }
            ],
            "dependsOnNodeKeys":[
                "node3"
            ],
            "appTags":[
                "appTag1",
                "appTag2"
            ],
            "urls": [
                {
                  "displayName": "Hyperglance API",
                  "urlPath": "https://www.hyperglance.com/api/",
                  "description": "API Reference in Hyperglance support Page”
                },
                {
                  "displayName": "Hyperglance",
                  "urlPath": "https://twitter.com/hyperglance",
                  "description": "Hyperglance Twitter Account"
                }
             ],
            "networkDetails":{
                "name":"name1",
                "ipAddresses":[
                    "1.2.3.4",
                    "4.3.2.1"
                ],
                "hostNames":[
                    "host1",
                    "host2"
                ],
                "dnsNames":[
                    "dns1",
                    "dns2"
                ],
                "macAddresses":[
                    "mac1",
                    "mac2"
                ]
            }
        },
        {
            "key":"node2",
            "name":"lab host1",
            "type":"host",
            "groupKey": "g1",
            "attributes":[
                {
                    "name":"Company",
                    "value":"Acme Corp."
                }
            ]
        },
        {
            "key":"node3",
            "name":"network-1",
            "type":"network",
            "groupKey": "g2",
            "attributes":[
                {
                    "name":"Company",
                    "value":"Acme Corp."
                }
            ]
        }
    ],
    "endpoints":[
        {
            "key":"ep1",
            "type":"virtual port",
            "nodeKey":"node1",
            "networkDetails":{
                "ipAddresses":[
                    "11.22.33.44"
                ],
                "macAddresses":[
                    "mac101",
                    "mac102"
                ]
            }
        }
    ],
    "links":[
        {
            "key":"link1",
            "type":"virtual<->physical connection",
            "endpointAKey":"ep1",
            "nodeBKey":"node2"
        }
    ],
    "alarms":[
        {
            "key":"alarm1",
            "name":"High CPU",
            "type":"metric alarm",
            "severity":"CRITICAL",
            "nodeKey":"node1",
            "attributes":[
                {
                    "name":"Description",
                    "value":"CPU exceeded threshold!"
                }
            ]
        }
    ],
    "groups": [
        {
             "key": "g1",
             "name": "group1",
             "type": "VPC",
             "attributes": [
                {
                    "name": "Description",
                    "value": "Small subset of Topology"
                }
            ]
        },
        {
             "key": "g2",
             "name": "group2",
             "type": "RDS",
             "parentGroupKey": "g1",
             "attributes": [
                {
                    "name": "Description",
                    "value": "Small subset of Topology"
                }
             ]
        }
     ]
}

JSON elements:

name
String
The unique name of the topology being created/updated.
Must be unique within the scope of the datasource.
nodes (optional)
List of Nodes
Nodes to be created/updated.
Any nodes created prior for this topology and are not present in this list will be removed.
endpoints (optional)
List of Endpoints
Endpoints to be created/updated.
Any endpoints created prior for this topology and are not present in this list will be removed.
links (optional)
List of Links
Links to be created/updated.
Any links created prior for this topology and are not present in this list will be removed.
alarms (optional)
List of Alarms

groups (optional)
List of groups
Groups to be created/updated.
Any groups created prior for this topology and are not present in this list will be removed.
key
String
An identifier that must be unique within this topology.
Valid on Nodes, Endpoints and Links.
type
String
A type indicator. May take any value.
Valid on Nodes, Endpoints and Links.
groupKey (optional)
String
Node will be created inside this group
parentGroupKey (optional)
String
The child group will be created inside this group
attributes (optional)
List of Attributes
Attributes to be created/updated
Valid on Nodes, Endpoints, Links, Alarms and Group.
name
String
The name of an attribute to be created/updated.
value
String
The value of an attribute to be created/updated.
dependsOnNodeKeys (optional)
List of Strings
Each string is a key of a node which “supports” the given node (which means that the given node is dependent on those)
appTags (optional)
List of Strings
Application tags which will be assigned to the given node
urls(optional)
List of External Links
The urls can be created/updated on the entities.
networkDetails (optional)
Object
Contains network details for a given a Node Endpoint.
Contains properties:
name, ipAddresses, hostNames, dnsNames, macAddresses
name (optional)
String
Name associated with the given node (Exclusive just for Node)
ipAddresses (optional)
List of Strings
IP addresses (IPv4 and IPv6) which assigned to the given Node or Endpoint
hostNames (optional)
List of Strings
The hostnames of the given Node (Exclusive just for Node)
dnsNames (optional)
List of Strings
The DNS names of the given Node (Exclusive just for Node)
macAddresses (optional)
List of Strings
The MAC addresses of the given Node or Endpoint
nodeKey (optional)
String
The Key of the node to attach to.
Only valid on Endpoints and Alarms.
On Endpoints one of nodeKey or nodeUID must be provided.
On Alarms one of nodeKey, endpointKey or ownerUID must be provided.
nodeUID (optional)
UID String
The UID of the node to attach to.
Only valid on Endpoints.
One of nodeKey or nodeUID must be provided.
nodeAKey (optional)
String
The Key of a Node to attach one end of a link to.
Only valid on Links.
Exactly one of nodeAKey, endpointAKey or fromUID must be provided.
nodeBKey (optional)
String
The Key of a Node to attach one end of a link to.
Only valid on Links.
Exactly one of nodeBKey, endpointBKey or toUID must be provided.
endpointAKey (optional)
String
The Key of an endpoint to attach one end of a link to.
Only valid on Links.
Exactly one of nodeAKey, endpointAKey or fromUID must be provided.
endpointBKey (optional)
String
The Key of an endpoint to attach one end of a link to.
Only valid on Links.
Exactly one of nodeBKey, endpointBKey or toUID must be provided.
fromUID (optional)
UID String
The UID of a node or endpoint to attach one end of a link to.
Only valid on Links.
Exactly one of nodeAKey, endpointAKey or fromUID must be provided.
toUID (optional)
UID String
The UID of a node or endpoint to attach one end of a link to.
Only valid on Links.
Exactly one of nodeBKey, endpointBKey or toUID must be provided.
endpointKey (optional)
String
The Key of the endpoint to attach to.
Only valid on Alarms.
One of nodeKey, endpointKey or ownerUID must be provided.
ownerUID
UID String
The UID of a node or endpoint to attach to.
Only valid on Alarms.
One of nodeKey, endpointKey or ownerUID must be provided.
severity
String
The severity of an Alarm.
One of: CRITICAL, SEVERE, WARNING, INFO.

Example response:

{
    "nodes": [
        { "key":"node1" "UID": "902c-8ce241a85bbb" },
        { "key":"node2" "UID": "9421-8bb2a8139669" }
    ],
    "endpoints": [
        { "key": "ep1", "UID": "8c73-e7f06f359a1f" }
    ],
    "links": [
        { "key": "link1", "UID": "becd-5c6d4c62b09c" }
    ],
    "alarms": [
        { "key": "alarm1", "UID": "898e-87ef7fed4dff" }
    ]
}

JSON elements:

nodes
Nodes that were created or updated in this topology.
endpoints
Endpoints that were created or updated in this topology.
links
Links that were created or updated in this topology.
groups
Groups that were created or updated in this topology.
alarms
Alarms that were created or updated in this topology.
key
The Key of the Node, Endpoint, Link or Alarm that was created or updated.
UID
The generated unique UID of the Node, Endpoint or Link that was created or updated.
Note: UIDs will not change once an entity is created; the UIDs of updated entities are the same as they were when those entities were first created.

Sample code:

  • examples/basic examples/create_topology.py

Topology API - Remove

DELETE /topology

Removes all topologies contributed by the HGAPI client application, or removes a single topology if called with a query parameter specifying an individual topology name.

Normal response codes: 202 Accepted, 204 No Content
Error response codes: 
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

Query parameters:

name (optional)
The name of a topology to remove. (Must be a topology that was contributed by the HGAPI client application).

Sample code:

  • examples/basic examples/delete_topology.py

Augmentation API - Attributes

PUT /augment/attributes

Specifies the set of attribute augmentations to apply to any pre-existing nodes, endpoints, links or alarms. Replacing all attribute augmentations provided in any prior invocation of this call made by the HGAPI client application.

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

 

Example request:

{
    "attributes": [
        {
            "UID": "acda-dee6d506a1db",
            "attributes": [
                { "name": "Contact E-Mail", "value": "jon@example.com" }
            ]
        }
    ]
}

JSON elements:

attributes
List of Attribute-Augmentations
Attribute-Augmentations to apply.
Any Attribute-Augmentations created prior by this data-source will be replaced.
UID
UID String
The UID of a Node, Endpoint, Link, Alarm or Group receiving the augmentation.
attributes
List of Attributes
Attributes to add to the Node, Endpoint, Link or Group.
Any Attribute-Augmentations created prior for the entity by this data-source will be replaced.
name
String
The name of an attribute.
value
String
The value of an attribute.

 

Sample code:

  • examples/basic examples/augment_attributes1.py
  • examples/basic examples/augment_attributes2.py

Augmentation API – Application Tags

PUT /augment/apptags

Specifies the set of application tags augmentations to apply to any pre-existing nodes.

Replacing all application tags augmentations provided in any prior invocation of this call made by the HGAPI client application.

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"]
        }
    ]
}

JSON elements:

appTags
List of Application-Tags-Augmentations
Application-Tags-Augmentations to apply.
Any Application-Tags-Augmentations created prior by this data-source will be replaced.
UID
UID String
The UID of a Node receiving the augmentation.
appTags
List of Strings
Each String is an application tag that will be associated to the Node that receiving the augmentation.

 

Sample code:

  • examples/basic examples/augment_appTags.py

Augmentation API – Depends On

PUT /augment/dependencies

Specifies the set of dependency augmentations to apply to any pre-existing nodes.

Replacing all dependency augmentations provided in any prior invocation of this call made by the HGAPI client application.

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

 

Example request:

{
    "dependsOn": [
        {
            "UID": "acda-dee6d506a1db",
            "dependsOn": ["898e-87ef7fed4dff", "988a-60aa3b19f13a"]
        }
    ]
}

JSON elements:

dependsOn
List of Dependency-Augmentations
Dependency-Augmentations to apply.
Any Dependency-Augmentations created prior by this data-source will be replaced.
UID
UID String
The UID of a Node receiving the augmentation.
dependsOn
List of UID Strings
Each UID in that list is associated with a node that supports the Node that receiving the augmentation.

 

Sample code:

  • examples/basic examples/augment_dependencies.py

Augmentation API – Entity Specific Urls

PUT /augment/urls

Specifies the list of external url augmentations to apply to any pre-existing nodes.

Replacing all external url augmentations provided in any prior invocation of this call made by the HGAPI client application.

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

 

Example request:

{
    "urls": [
        {
            "UID": "acda-dee6d506a1db",
            "urls": [
                {
                  "displayName": "Hyperglance API",
                  "urlPath": "https://www.hyperglance.com/api/",
                  "description": "API Reference in Hyperglance support Page"
                }
             ]
        }
    ]
}

JSON elements:

urls
List of urls -Augmentations
Url-Augmentations to apply.
Any Url-Augmentations created prior by this data-source will be replaced.
UID
UID String
The UID of a Node or Group receiving the augmentation.
urls
List of urls
Each url in that list is associated with a node or group receiving the augmentation.
Url consists of displayName, description and urlPath fields.

 

Sample code:

examples/basic examples/augment_ urls.py

Python Code Samples

A selection of Python code samples that demonstrate the use of the API are located in the SDK/examples subdirectory.

These samples were written against Python 3.4, but may work in newer versions too.

Running the Samples

  1. Open a browser and visit : hyperglance admin panel https://IP_address/#/admin.
  2. Select the 'API' section to create a unique API key via 'Register App'.
  • Register a new App by entering a suitable Datasource name (for example call it: AcmeApp) and giving it a helpful label/description.
  • Note the API key that is generated. Keep this safe and treat it like a password!
  • Open SDK/examples/basic examples/config.py in a text-editor.
  • Set the DATASOURCE and API_KEY values to match those from steps 2 and 3 above.
  • Set the HGS_URL value to the URL of your Hyperglance Server (including the port if not using the default 443 port).
  • Ensure that the Python interpreter is on your PATH. On Windows Python 3.4 is installed under: C:\Python34
  • To run a Python script, launch a command-line shell and type: python name_of_script.py