PowerShell and the REST API for the IT pro

Dr

February 21st, 2018

Summary: This post provides a quick introduction to what the REST API is, and how it applies to Windows PowerShell.

Q: Hey, Scripting Guy! I can see there is this cool cmdlet called Invoke-RestMethod. I’ve been told REST API’s are all around, and this allows me to consume that data. Could you give me a hand getting started? —SH

A: Hello SH, Glad to help out! I remember hearing about REST APIs the first time, thinking they might be a way to take a nap at work. Was I wrong on that one!

What a “REST API” is at the most BASIC level is really just a very fancy web Endpoint. You could, if you were really creative, type in everything you need to connect to one in your browser. But that wouldn’t be a very productive use of time.

What REST stands for is “Representational State Transfer.” It’s a very connectionless protocol. This means it shouldn’t care if there is a temporary break in the internet.

You can connect, ask it a question, and even in some cases send data. It will think about that question and can return content back (if so designed).

Generally, when you are contacting a REST API, you will need to provide some information. You also need to understand the “buzzwords” when you’re reading documentation for a REST Endpoint.

A URI or Endpoint

This will be an HTTP or HTTPS endpoint. It could be as detailed as this: https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1

Or it could be as simple as this: https://blogs.msdn.microsoft.com/powershell/feed/

Method

In all cases, you will be providing a “method.” This is similar to the verb in PowerShell. With REST, there are a few pretty common ones like PUT, GET, or POST. There are others like DELETE and PATCH. Which method you use is defined by the documentation of the owner of the REST API.

Authentication

Some REST API’s will not require authentication. A weather one might be an example, since no critical data is passing over the wires.

A REST API hosted by a Human Resources application would more than likely prefer authentication. They would need to know who is accessing that data, as part of its control mechanism.

Authentication could be a regular authentication pop-up for an ID and password. It could also be something like an access token, a temporary key generated initially and used for short term access uses.

Headers and the body

Headers and the body contain parameters and data we need to send up to the API. A good example of a header parameter might be the UserAgent string to identify your browser to the API. The body could be the raw data you need sent to a Translation API.

Knowing how these values can be consumed by Windows PowerShell, and how you can find which ones to use, are the trick to using a REST API.

Another hint you can use to learn what a REST method wants will be examples of the “Responses” documented for REST API’s. Take a look at the following example:POST /synthesizeHTTP/1.1Host: speech.platform.bing.com

Reading down line by line, you can see this particular operation is calling for a “POST” method. If you read the documentation on this particular function, you would notice that Content-Type is an actual value beyond supplied, as was X-Microsoft-OutputFormat.

Over the next few articles, we will be using PowerShell to consume the Azure Cognitive Services Text to Speech API, by using Invoke-RestMethod. My hope is that not only will you learn something cool, but you’ll have a bit of fun having Azure talk for you.

Stay tuned until next time, when we look at Azure Cognitive Services and getting some basic authentication happening for our little project.

I invite you to follow “Hey, Scripting Guy!” on Twitter and Facebook. If you have any questions, send email to them at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum.