Start Guide to CloudIQ REST API Using Postman

Start Guide to CloudIQ REST API Using Postman

This blog post will focus on the first steps to leverage the CloudIQ REST API. CloudIQ is the AIOps application that provides proactive health monitoring, recommendations, and predictive analytics for Dell infrastructure systems. You can use this API to access inventory, configuration, performance, capacity metrics, etc., for any systems available in CloudIQ. The CloudIQ API is divided into two functional areas: one enables access to resources and attributes, and the other enables access to metrics over time. This API is useful for anyone who wants to integrate CloudIQ with other tools they have in their ecosystem (such as CMDB, data warehouse, provisioning, and so on). We will use one of the most popular tools for working with RST APIs: Postman (although there are others, such as Swagger and curl). So, ready to unleash the power of APIs? With just one blog read and 30 minutes, you will be just moments away from transforming your IT service management!

The Postman API client (we’ll call it Postman in this doc for simplification) is a free and easy-to-use tool that allows developers to test and debug their REST APIs. It supports all the standard HTTP methods and enables developers to easily send requests to an API and view the responses. Postman also provides various other features that make working with REST APIs easier. For example, it allows developers to save and organize their requests and create and share collections of requests. It also has built-in support for authentication and authorization, a requirement for CloudIQ APIs

 

Getting Access: ClientID and Client Secret

First things first, before we get to Postman, we need to tackle authentication and authorization. So let’s get your OAuth2 client credentials (Client ID and Client Secret) - as mentioned, CloudIQ REST API uses OAuth 2.0 protocol for authentication and authorization. Do not worry, I have sketched out the process in six easy steps below:

1. Log in to CloudIQ
2. Under the Admin section in the left sidebar, click on Integrations. If you cannot see Admin > Integrations in the left sidebar, then you must first get a CloudIQ DevOps Role. Proceed to step 3 if you need the role assigned. If you can see and navigate to Admin > Integrations, then proceed to step 4.
3. A CloudIQ DevOps Role is required to invoke and utilize the CloudIQ REST API. This role can be assigned by a CloudIQ Admin (a.k.a., Company Admin)  from the Identity Management menu on the sidebar under Admin. Note that CloudIQ Admins are automatically mapped to Dell Support Accounts that have been defined as Company Admins. As shown in Figure 1, the Identity Management option is not present, which means this user is not a CloudIQ Admin. You can refer to the following article on Dell’s support site to determine who the Admins are. Also, additional details on using MyService360 for company administration can be found here.
4. Once your user account has access to the Integrations menu, select the API tab and click on CREATE API KEY blue box that showed up
5. A new window will pop up, complete the information: Name (unique and cannot be duplicated) and Description (add information on what that API is for)
6. Look for the recently created key and click on View Key. A new window will pop up; look for the Auth Information.

 

Figure 1: Five Steps to get ClientID and Client Secret

Congratulations, you now have your credentials and authorization! Now, you need to copy the Client ID and Client Secret (rotation policy is 12 months), which will be your credentials to access the REST API via OAuth 2, leveraging the client credentials Grant Type. But no worries, we will talk more about that now.

 

Postman: Authentication & Authorization

Before starting with Postman, remember that the API key will be available after a delay of 5 to 10 minutes. This link will provide helpful information about Postman for further reading in case you want to expand your knowledge. But stay with me for the CloudIQ example for now. Quick comment: Signing up for a Postman account is optional, and you can use the Postman desktop app without an account if you prefer. If you want to create a Postman account, you can continue to sign up for a Postman account here.

Once inside Postman, you can import a collection or create a new one from scratch (as shown in Figure 2). To make it easier, we have already built an with many API calls as guidance, which you can access in this JSON file in this link, by going to /rest_api subfolder. Once you open your workspace inside Postman, you can Import an existing collection by clicking on the three lines in the upper left corner > File > Import…

Figure 2: Import a collection in Postman

The first thing you need to do to start using the GET and POST examples imported is to get your Token so that you don’t receive this 401 Unauthorized message response:

Figure 3: 401 Unauthorized message response (not having configured OAuth2)

The Authorization should be done at a collection level, so it works for all API calls inside that collection, but it can also be done inside a particular API request. To do so in the collection, please follow these five steps:

1. Click on the collection name "CloudIQ REST API Examples"
2. Under the Authorization tab, complete the information as shown in Image 4 ("OAuth 2.0" & "Request URL")
3. Continue completing Configure New Token:
   1. Token name will be populated in the end
   2. Set the Grant Type as "Client Credentials"
   3. Access Token URL as " https://cloudiq.apis.dell.com/auth/oauth/v2/token"
   4. Client ID and Client Secret will be the ones you generated when creating API Key
   5. Set Scope as "oapi"
   6. Set Client Authentication as "Send as Basic Auth header"
4. Click on Get New Access Token
5. Finish by clicking Proceed and then Use Token

 

Figure 4: Authentication in Postman (at collection level)

I recommend setting the ClientID, Client Secret, and Token name as variables. To do so, you can double-click on each one of the alphanumeric codes and select "Set as variable", as shown in Image 5. A new window will pop up and offer you to set a new variable by completing Name and selecting Scope. The Token generated will last for 60 minutes.

Figure 5: Setting Client Secret as variable

Once the authentication process is complete at a collection level, any API request we send should trigger a 200 OK Status. For the most common Status Response Codes, please reference Table 1:

Table 1: Most common Status Response Codes

Now that authentication is covered, you can start sending API calls!

 

Section 3 – Postman: Collection

In the shared collection, you will find many GET and POST requests filled out with the URL needed. All of them will begin with: https://cloudiq.apis.dell.com/cloudiq/rest/v1 

All requests should have the authorization type preset to "Inherit auth fr…" which will automatically generate the authorization header from the postman collection, which will be OAuth 2.0: "This request is using OAuth 2.0 from collection CloudIQ REST API Examples."

The easiest request to start with is a Basic System Information GET request; for example: complete the base URL with "/systems" suffix and query all systems (across all products!) in one single REST API call.
GET-> https://cloudiq.apis.dell.com/cloudiq/rest/v1/systems 

This call will return a JSON payload with all the systems monitored in CloudIQ and available via the REST API. From now on, we will call those URLs endpoints and the information attributes from that system. Getting information about a particular system is only a matter of knowing how to specify it. Please, refer to Table 2, with all the resources (objects) available via CloudIQ REST APIs. So, for example, to GET information about storage systems, we need to call a particular endpoint, in this case, adding the "storage_systems" suffix to the base URL: GET->  https://cloudiq.apis.dell.com/cloudiq/rest/v1/storage_systems 

Table 2:  Object data and URL to add in REST APIs for CloudIQ

Dell has also introduced an endpoint to query time-series / metrics over time. You can use the /metric-metadata to list over 250 metrics from different objects. Some examples would be: GET-> 

https://cloudiq.apis.dell.com/cloudiq/rest/v1/metric-metadata/inlet_temperature_server_system 

https://cloudiq.apis.dell.com/cloudiq/rest/v1/metric-metadata/cpu_usage_percent_server_system 

Dell is continuously adding more components, attributes, and metrics to the CloudIQ REST API, so please check the documentation regularly to learn more: https://developer.dell.com/apis

We can filter things and get specific information using parameters such as select and filter. GET-> 

https://cloudiq.apis.dell.com/cloudiq/rest/v1/server_systems?select=health_score , health_state, health_issue_count&filter=health_score GT 90

The request mentioned above is to look for PowerEdge systems with health scores greater than ("GT") 90, and it will only return information on those systems related to health score, health state, and health issues count (as specified by the select command in the URL). More information regarding all the operators can be found in Table 3 in the appendix.

 

Use Case

Let’s say you want to track power consumed by a set of servers in your data centers so that you can estimate energy costs or carbon footprint for a given workload. First of all, we can leverage GET requests to start getting a sense of what the picture looks like.

Example: https://cloudiq.apis.dell.com/cloudiq/rest/v1/server_systems 

You can get all the server systems connected to CloudIQ; this sometimes can be overwhelming due to the number of instances we receive as a response. Suppose you are particularly interested in a specific location, like Tokyo; you can set up a filter to identify the PowerEdge servers in that location with the following GET request: https://cloudiq.apis.dell.com/cloudiq/rest/v1/server_systems?filter=location  like 'TOKYO'

In that URL, you can replace TOKYO with any location where you are interested in getting information.

Finally, we can add a filter to only see the power consumption and power state for all the server systems filtered:

https://cloudiq.apis.dell.com/cloudiq/rest/v1/server_systems?filter=location  like 'TOKYO'&select=power_consumption,power_state

The URL of the POST request (and yes, you will have changed from GET to POST for this specific query) is the following: https://cloudiq.apis.dell.com/cloudiq/rest/v1/metrics/query 

To get the historical data for those systems (for this example, we are interested in a particular 24hs window), you need to modify the body of this request. After selecting raw and then JSON in the dropdown, you can copy and paste the following payload:

{

  "from": "2022-11-13T00:00:00Z",

  "to": "2022-11-14T00:00:00Z",

  "resource_type": "server_system",

  "ids": [

         " ",

         " ",

         " ",

         " "

  ],

  "interval": "PT15M",

  "metrics": [

       "inlet_temperature",

        "power_consumption",

        "cpu_usage_percent"

  ]

}

Image 6: JSON body for Time series Query Example

 

In that query, you can change, add and remove server names, change the interval (for all intervals, please refer to Table 4), and change the metrics you want to collect.

 

Summary

Let’s take a look back at what we have covered above. We have walked through the basic steps needed to set up and configure the CloudIQ REST API and learned how to obtain credentials and Authenticate inside Postman. To get your feet wet, we have reviewed a Postman collection with more than 30 GET and POST requests and finally went through a couple of typical use cases.

If you would like to learn more about CloudIQ webhooks and REST API, you can visit the Dell Developer portal. We’d love to hear from you. If you have any questions, comments, or requests, please reach out via the CloudIQ feedback bottom.

Thanks for reading, and stay tuned for more insights on CloudIQ.

 

More CloudIQ posts

• CloudIQ Webhooks in Action
• Interacting with CloudIQ REST API using Python
• CloudIQ Webhook Integration: BigPanda Example
• CloudIQ Webhooks in Action

 

 

Appendix - Additional information

Operator	Meaning	Numeric	String	Enum
eq	Equal	Y	Y	Y
ne	Not equal	Y	Y	Y
gt	Greater than	Y	Y	Y
ge	Greater than or equal	Y	Y	Y
lt	Less than	Y	Y	Y
le	Less than or equal	y	Y	y
like	Simple substring match		Y
like	Case insensitive substring match		Y
()	Parentheses – used to group operations in standard manner.
not	Reverses the following operator
and	ANDs 2 filters, each in required parentheses
or	ORs 2 filters, each in required parentheses

Table 3: Valid Operator Values and their meaning

 

 

Operator	Collection Interval
PT5M	Five minutes
PT15M	Fifteen minutes
PT1H	One hour
P1D	One day

Table 4: Collection intervals

 

© 2023 Dell Inc. or its subsidiaries. All Rights Reserved. Dell Technologies is a trademark of Dell Inc. or its subsidiaries. Dell Technologies believes the information in this document is accurate as of its publication date. The information is subject to change without notice.