HPE IMC RESTapi

IMC for day to day management of traditional network devices is ‘ok’. I can tell if a device is alive and with quite a bit of effort I can get HPE’s management system to provide some information like if the device sent a specific trap. It is good at understanding HPE devices (as you would expect) so it understands that a IRF stack is multiple physicals acting as a single logical device. It can provide some graphs (with a lot of effort) showing long term trends.

It does however let me down in so many ways. Running tasks against a large number of devices often fails. Running a check or gathering info from a group of devices is problematic and often fails. When it fails you don’t get a reason and you don’t get informed.

To put a positive spin on the system we have a database of devices that are auto-discovered and without much work the basic facts are continuously recorded. With the right overlay this can be exploited to provide a good solution. However, to make that happen IMC needs a really good way to interact with it. Luckily it does..

Introduction

A RESTful API is an attempt to provide a standardised mechanism to interact with a server.

REST = representational state transfer (REST)

API = application program interface

It uses HTTP requests to ask questions and send commands. The response comes in a structured HTTP response. If you tell IMC to do something the response will be ‘OK’ or ‘NOT OK’. If you ask a question the response will include the answer. For most API implementations I’ve come across including Aruba’s Airwave that response is in XML format. It is an industry standard that can be used in a wide range of applications. By default IMC does the same. You can however request the response is structured JSON which is brill because this format is much more usable within Ansible. XML data requires a module to kind of translate into Ansible variables where as JSON can be used natively. In fact Ansible modules will return results in JSON.

Example

Sending the following URL to an IMC server will provide you with the first ten devices in the database.

https://imc.constantpinger.com:443/imcrs/plat/res/device?resPrivilegeFilter=false&start=0&size=10&orderBy=id&desc=false&total=false&exact=false

If you paste this into a browser you’ll get XML (default). If you send an additional piece of info (headers) in the request you’ll get JSON. An example device looks like this:

{
  "device": {
    "id": "2",
    "label": "avswbk018",
    "ip": "10.4.204.7",
    "mask": "255.255.255.0",
    "status": "1",
    "statusDesc": "Normal",
    "sysName": "avswbk018",
    "contact": "itsupport@york.ac.uk",
    "location": "Biology B/K/018",
    "sysOid": "1.3.6.1.4.1.11.2.3.7.11.117",
    "sysDescription": "HP J9565A Switch 2615-8-PoE, revision A.15.16.0008, ROM J.14.08 (/ws/swbuildm/rel_orlando_qaoff/code/build/lgr(swbuildm_rel_orlando_qaoff_rel_orlando)) (Formerly ProCurve)",
    "devCategoryImgSrc": "switch",
    "topoIconName": "iconswitch",
    "devPingState": "1",
    "categoryId": "1",
    "symbolId": "1004",
    "symbolName": "avswbk018",
    "symbolType": "3",
    "symbolDesc": "",
    "symbolLevel": "3",
    "parentId": "1003",
    "typeName": "HPE 2615-8-PoE Switch",
    "mac": "d8:9d:67:ff:5e:10",
    "link": {
      "@op": "GET",
      "@rel": "self",
      "@href": "https://imc.abc.com/imcrs/plat/res/device/2"
    }
  },
  "link": {
    "@op": "GET",
    "@rel": "next",
    "@href": "https://imc.abc.com/imcrs/plat/res/device?start=1&size=1&resPrivilegeFilter=false&total=false&exact=false&orderBy=id&desc=false"
  }
}

Web Interface

If you have a working IMC server you can go to a web page at https://<imc>/imcrs/ which is a portal to the RESTful API. It is a portal to allow humans to work with the API designed for systems that don’t need humans. Or to put it a better way an interface to help the engineer explore the API in an interactive manor. All the info is available in documents but this interface allows you to run API calls and see the results. It makes it very easy to craft the URLs you need to get information or make changes.

Be warned, it is live and you have the ability to kill you IMC implementation with a single click.

Below is an example screen with the device section expanded. This device section is where you go to query the device database. See my post about using IMC and Ansible for an example of this in use.

The User Guide link in the top right is really useful as it links to the API reference. This provides the XML structure for what is returned for every call together with some brief explanations about the parameters you need to send. Note some parameters are mandatory for example an ID integer when requesting details of a device. There is no JSON output in this help so you need to run a command in the main interface if that is the flavor you are after.

Example API Calls

• Get the last 50 unrecovered alarms:
• https://imc.abc.com:443/imcrs/fault/faultRealTime?operatorName=bob2

• Get the full list of devices in IMC
• https:// imc.abc.com :443/imcrs/plat/res/device?resPrivilegeFilter=false&start=0&size=99999&orderBy=id&desc=false&total=false&exact=false

• Kick of an autodiscover
• https:// imc.abc.com :443/imcrs/plat/res/autodiscover/start
  • body:

<autoDiscoverConfig>
  <mode>0</mode>
  <ipSection>
    <begin>144.32.226.97</begin>
    <end>144.32.226.98</end>
  </ipSection>
  <sendTrap>true</sendTrap>
</autoDiscoverConfig>