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.

For some excellent examples that we are going to work with in upcoming articles, see the Azure Cognitive Services REST API.

When we are building values for a header in PowerShell for Invoke-RestMethod, the format will look like this for the most part: @{‘Valuename’ = ‘SomeValue’ }

An example you will see early on is passing the header needed for the authentication component of the REST API. It will look like this: $Header=@{‘Ocp-Apim-Subscription-Key’ = $APIKey }

Or, a more complex one would look like this: $Header=@{ ` ‘Content-Type’ = ‘application/ssml+xml’; ` ‘X-Microsoft-OutputFormat’ = $AudioOutputType; ` ‘X-Search-AppId’ = $XSearchAppId; ` ‘X-Search-ClientId’ = $XSearchClientId; ` ‘Authorization’ = $AccessToken ` }

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 /synthesize HTTP/1.1 Host: speech.platform.bing.com

X-Microsoft-OutputFormat: riff-8khz-8bit-mono-mulaw Content-Type: application/ssml+xml Host: speech.platform.bing.com Content-Length: 197 Authorization: Bearer [Base64 access_token]

<speak version=’1.0′ xml:lang=’en-US’><voice xml:lang=’en-US’ xml:gender=’Female’ name=’Microsoft Server Speech Text to Speech Voice (en-US, ZiraRUS)’>Microsoft Bing Voice Output API</voice></speak>

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.

Sean Kearney, Premier Field Engineer

Enterprise Services Delivery, Secure Infrastructure