HMC REST APIs

Learn about IBM® Power Systems Hardware Management Console (HMC) Representational State Transfer (REST) application program interfaces (APIs). REST is a style of web service, hosted by a web server. In REST, the web server focus is on managing nouns. Nouns represent known things like logical partitions, managed systems. Each noun has a unique identity. GET, PUT, POST, and DELETE HTTP methods are used to act on the nouns. Internet Media Type (MIME Type) identifies the types of data. HTTP request headers, response headers, and status codes are a vital part of the application. The addition of hyper links into the data content of the nouns expands the REST web services into a richer web application.

The HMC provides systems administrators a tool for planning, deploying, and managing IBM Power Systems servers.

HMC provides functions such as IBM Power Systems hardware management and virtualization (partition) management.

The HMC REST web services provide the following services:

  1. Power Systems server virtualization
  2. Performance Capacity and Monitoring
  3. Power® Enterprise Pools (CoD)

Programmatic consumers of HMC REST web services are:

  • A web-based client capable of using Atom Publishing Protocol and XML payloads.
  • A client that can communicate over HTTP protocol and parse XML content.
    • Examples include the following programming languages: Python, Java™, Ruby, PHP, C++, C#

URL Model

  • Design goals:
    • Simple URL patterns
    • Polymorphic URL patterns
    • Use Atom Publishing Protocol
    • Enable rich web application
    • Use polymorphic job pattern when asynchronous or RPC style interactions required
  • Concepts:
    • Anchor URL patterns provide services for a type of root/child element
    • Instance URL patterns provide services for a uniquely identified root/child element
  • URL Pattern Grammar building blocks:
    • {R} root element type
    • {C} child element type
    • {D} detail element type. {D} can be accessed as part of {R} or {C}
    • {UUID} a unique UUID value
    • {OP} the name of a type of job (an operation)
    • {QUERY} a search query
    • {JOBID} the ID of a submitted job
    • {QP} a quick path variable name
    • {EXTENDED} extended group list

HTTP Port

HMC REST web services operate on 12443 HTTP Port. The following URL is an example of the full URL that must be used to get the management console information:

https://{HMC}:12443/rest/api/uom/ManagementConsole. Here, HMC can be the IP address of the HMC or the host name of the HMC.

URL Model Use Cases for Root Elements

  • ROOT ANCHOR URL patterns:
    • /rest/api/uom/{R}/operations ----------> get the defined job operations for {R}
    • /rest/api/uom/{R}/jobs ----------------> get all known jobs for {R}
    • /rest/api/uom/{R}/quick ---------------> get the defined quick properties for {R}
    • /rest/api/uom/{R}/quick/all -----------> get a list of all defined quick properties for type {R}
    • /rest/api/uom/{R}/search --------------> get the defined search parameters for {R}
    • /rest/api/uom/{R}/search/{QUERY} ----> get the feed of instances of {R} matching the query
    • /rest/api/uom/{R} ---------------------> get the feed of all known instances of {R}
  • ROOT INSTANCE URL patterns:
    • /rest/api/uom/{R}/{UUID}/do/{OP} -------> get a template for job of type {OP}
    • /rest/api/uom/{R}/{UUID}/jobs -----------> get all known jobs for this element of {R}
    • /rest/api/uom/{R}/{UUID}/jobs/{JOBID} -> get the details for the one job
    • /rest/api/uom/{R}/{UUID}/quick/{QP} ----> get the quick property value of {QP}
    • /rest/api/uom/{R}/{UUID} ----------------> get the XML details of this instance of {R}

URL Model for Child Elements Uses the Same Patterns. (Must be anchored to an instance of a parent Root Element)

  • CHILD ANCHOR URL patterns:
    • /rest/api/uom/{R}/{UUID}/{C}/operations ----------> get the defined job operations for {C}
    • /rest/api/uom/{R}/{UUID}/{C}/jobs ----------------> get all known jobs for {C}
    • /rest/api/uom/{R}/{UUID}/{C}/quick ---------------> get the defined quick properties for {C}
    • /rest/api/uom/{R}/{UUID}/{C}/search --------------> get the defined search parameters for {C}
    • /rest/api/uom/{R}/{UUID}/{C}/search/{QUERY} -----> get the feed of instances of {C} matching the query
    • /rest/api/uom/{R}/{UUID}/{C}/ ---------------------> get the feed of all known instances of {C}
  • CHILD INSTANCE URL patterns:
    • /rest/api/uom/{R}/{UUID}/{C}/{UUID}/do/{OP} ------> get a template for job of type {OP}
    • /rest/api/uom/{R}/{UUID}/{C}/{UUID}/jobs ----------> get all known jobs for this element of {C}
    • /rest/api/uom/{R}/{UUID}/{C}/{UUID}/jobs/{JOBID} -> get the details for the one job
    • /rest/api/uom/{R}/{UUID}/{C}/{UUID}/quick/{QP} ---> get the quick property value of {QP}
    • /rest/api/uom/{R}/{UUID}/{C}/{UUID}/ ---------------> get the XML details of this instance of {C}

Schema Definition File

Every {R} or {C} or detailed object is bound by rules defined in a corresponding XML schema file. Using the URL pattern described, any object schema definition can be fetched.

  • /rest/api/web/schema/{R}.xsd ----> Substitute the {R} for Root Object
  • /rest/api/web/schema/{C}.xsd ----> Substitute the {C} for Child Object
  • /rest/api/web/schema/{D}.xsd ----> Substitute the {D} for Detailed Object

Extended Group

The complete set of attributes that are defined under different HMC objects and supported by REST APIs are classified under different groups. List of all supported groups is provided below:

  • None - Get none of the supported extended group attributes for an object type. Get only the default attributes.
  • Advanced - Group of attributes that are classified as Advanced.
  • SystemNetwork - Attributes and objects that are related to Managed System's Virtual Network.
  • ViosStorage - Objects that are related to Storage managed by VIOS.
  • Hypervisor - Attributes and objects that are retrieved from Hypervisor.
  • ViosNetwork - Objects that are related to Virtual Network managed by VIOS.
  • ViosFCMapping - List of configured VirtualFibreChannelMapping.
  • ViosSCSIMapping - List of configured VirtualSCSIMapping.

An attribute that is not classified under any of the defined groups is implicitly assumed to be classified under group Default. The users of the APIs can use the groups by passing one or more extended groups as query parameter. The extended group is supported by HTTP methods - GET, PUT, POST, and DELETE.

Usage

If an object does not support any known extended group that is defined, calling the URL with group=None might result in HTTP Status code 400 Bad Request response

  • /rest/api/uom/{R}?group={EXTENDED} ---------------------> Supports one or more of query parameters gets {R} with mentioned extended group
  • /rest/api/uom/{R}/{UUID}?group={EXTENDED} ---------------------> Supports one or more of query parameters gets {R}/(UUID) with mentioned extended group
  • /rest/api/uom/{R}/{UUID}/{C}?group={EXTENDED} ---------------------> Supports one or more of query parameters gets {C} with mentioned extended group
  • /rest/api/uom/{R}/{UUID}/{C}/{UUID}?group={EXTENDED} ---------------------> Supports one or more of query parameters gets {C}/(UUID) with mentioned extended group