RedFish RESTful APIs with Postman

There is no TL;DR this week because this is a short one and we dive right in, so keep reading!

This week, we’re doing the basics of REST APIs with Postman. Specifically, it just so happens we’ll be looking at the RedFish API, which is a standard by the DMTF. The official definition of the Redfish specification is:

“Redfish is a standard that uses RESTful interface semantics to access a schema based data model to conduct management operations. It is suitable for a wide range of devices, from stand-alone servers, to composable infrastructures, and to large-scale cloud environments.”

Furthermore, without delving into the history of REST APIs, the, “explain it to me like I’m a Dumb SysAdmin” definition is that it’s a defined directory structure that is accessible using the standard HTTP/HTTPS GET/POST/PUT/DELETE (etc.) methods to perform some action on the application in question. The beauty of it is that REST APIs have become a ubiquitous and well-known method for anyone to interact with an application, so we’re, “getting devvy” as I like to call it.

I have actually never said that ever, but . . . let’s just go with it.

You don’t have to be a REST guru, but the basics of REST are assumed knowledge these days if you are going to be a Cloud Engineer and/or use IaC, in my humble opinion. You can add this one to your resumé, as it were.

Real-World Examples of REST API Use:

1. Through the RESTful API for HPE iLO, I am able to report BIOS settings that would only be seen through a local console reboot. This is the example you will see later in this post.
2. I was able to collaborate with one of our developers (like a big boy with big boy pants!) on our Morpheus Cloud Management Platform (Ooohhh! I should post on that someday!).
3. I was able to use the Ansible uri module to do something that I could not do by any other means.
4. Although I didn’t really code it out myself, we had a contractor use PowerCLI with REST APIs for monitoring our ESXi hosts beyond your typical ICMP monitoring, which I thought was a pretty cool idea.

These are only some examples; I have used REST APIs and Postman quite heavily for anything from performing actions on servers, to getting me out of bind, to just straight getting people information in a way they can actually use.

One additional advantage is that input and output to and from REST is usually in the form of JSON. Need a list of attributes or settings that need to be applied to a server? Pull them through a GET and then alter the settings, then POST the new settings onto the machine, or multiple machines in an automated way.

REST API Documentation and Basics

The real-world situation is this:

At my work, we change the Thermal Configuration of some of our servers to “Optimal Cooling” for reasons too numerous to go into here. All you need to know is that it has to do with fan noise. With REST, we can easily verify the Thermal settings without having to reboot the server. Without REST, as far as I know, we’d have to schedule a maintenance window and reboot the server . . . just to verify those settings. That is not fun. . . . Like at all.

First things first: Read the REST API documentation for what you are accessing. Your knowledge of web servers will come in handy here, because, in my humble opinion, it’s all about hierarchical “subdirectories”. Sifting through the documentation linked above, it looks like we want to perform a GET on /rest/v1/Systems/1/BIOS.

You need 4 things to connect to a REST API:

1. The uri. In this case it’s https://ilohostnameorip/rest/v1/Systems/1/BIOS.
2. The method: GET, POST, PUT, and so on. In this case we want to use GET because we are simply reporting the output, not changing anything. Think of it as a read-only query.
3. The method of authorization. The iLO supports Basic Auth, so that’s what we will use. It’s easy and repeatable. An additional very common method is OAuth Token Based Authorization, but that goes beyond this post. You’ll have to read the documentation to find this information.
4. Header information. This is also very common. One common header that I have found is Content-Type. Sometimes, the REST API in question will require these so that the output is formatted properly.

The good news is that in most cases, I have found that the REST API documentation should have all of the information you need.

Postman Basics

There are many tools for connecting to a REST API. curl is one tool. Powershell has its Invoke-RestMethod. But today we are going to use Postman. Let’s use it to see if an HPE Gen 10 Server is set to OptimalCooling through its iLO REST API. I recommend Postman highly, by the way. You should have it as part of your standard Toolbox, along with an IDE Editor, Git, and nmap, among others. So if you don’t have Postman, go ahead and install it. I’ll wait . . .

Welcome back!

A disclaimer: I am very well aware, Postman experts reading this with arms folded and skeptical furrowed brow, that Postman does far more than what I am about to describe here. This post isn’t entitled, “RedFish REST APIs with Postman Deep Dive” now, is it? We’re really covering two topics here, and the REST API concepts in general are just as important, so we’re going to do a very simple GET method to see all BIOS settings on a Gen 10 Series Server using REST.

Once you have Postman opened, it is likely that there are a series of prompts. Once you make your way through them, you should have a blank workspace. Get your Postman to look like this:

Click the + sign to open a new tab and start a new REST API connection.

It defaults to GET as the method, so you can leave that drop down at the default.

In the box with the text, “Enter request URL,” enter the URL for your iLO by IP address or name and the REST API uri reference. It should be this:

https://ilohostnameorip/rest/v1/Systems/1/BIOS

Click the Authorization tab and choose Basic Auth as the TYPE.

Plug in the Admin Username and Password for the iLO. It should look like this, once complete:

And that’s it.

Click the Send button and the Body of the request will come back as JSON. Look for “Attributes“. Somewhere down the list you will find what we’re looking for in this example, “ThermalConfig”. You can also use Ctrl+F to find “ThermalConfig” in the list. It will look something like this (I took out some extraneous entries to make this shorter, but left enough in so you get the idea):

. . . 
"Attributes": {
        "AcpiHpet": "Enabled",
        "AcpiRootBridgePxm": "Enabled",
        "AcpiSlit": "Enabled",
        "AdjSecPrefetch": "Enabled",
        "AdminEmail": "",
        "AdminName": "",
        "AdminOtherInfo": "",
        "AdminPhone": "",
        "AdvCrashDumpMode": "Disabled",
        "AdvancedMemProtection": "AdvancedEcc",
        "AsrStatus": "Enabled",
        "AsrTimeoutMinutes": "Timeout10",
        "AssetTagProtection": "Unlocked",
        "AutoPowerOn": "RestoreLastState",
        "BootMode": "Uefi",
        "BootOrderPolicy": "AttemptOnce",
        . . . 
        "ThermalConfig": "OptimalCooling",
        "ThermalShutdown": "Enabled",
        "TimeFormat": "Utc",
        "TimeZone": "Utc0",
        . . .
        "iSCSIPolicy": "SoftwareInitiator"
    },
. . . 

As you can see, this is a very simple example. Some REST APIs allow for you to jump up and down through the directory structure and you can find a lot of things by simply using trial and error, although you’d have to ensure that you aren’t breaking changing anything as you move your way through the REST API.

Notice that Postman allows you to save these REST API connections for later. This is advantageous for repeating your connections, or if the REST API connection is especially complex.

Start connecting to some REST APIs at your work (non-prod machines, of course!) and start looking at the additional options needed to connect, such as the Headers and so on.

Before you’ll know it you’ll be manipulating REST APIs with the best of them!

Questions? Hit me up on twitter @RussianLitGuy or email me at bryansullins@thinkingoutcloud.org. I would love to hear from you.