How to Use PowerShell to Monitor REST APIs

This article explains how to use PowerShell to monitor REST APIs. 

One aspect of PowerShell that is often overlooked is it's native ability to communicate with APIs. These days, it seems like there's an API for just about everything and it's becoming increasingly important to know how to communicate with these APIs in code. Being able to write code to interact with an API can prove handy in some different situations.

Let's first define what I mean by "REST API." Without going into a lot of software development jargon, a REST API can just be thought of as an URL that contains an XML file that allows the user to interact with some service behind it. For example, Twitter has a REST API. With this API, you can send tweets, read users' timelines, send direct messages and so on. This API allows the user to perform just about anything that can with the GUI application via code to create your application around Twitter or just automate some stuff with PowerShell.

Since each web service can structure their REST API differently, I've chosen to use a generic REST API to demonstrate what's possible with PowerShell. To work with a REST API, we'll need some way to send HTTP commands to it. We could choose to use the Invoke-WebRequest command, but PowerShell has a command already pre-designed to exclusively work with REST APIs known as Invoke-RestMethod. This command removes a lot of the complications around working with APIs.

Related Article: What is Pester for PowerShell

To demonstrate how Invoke-RestMethod works, let's first attempt to read some information from our demonstration API. To read information, we use the GET verb. Luckily Invoke-RestMethod has a Method parameter that allows us to easily pick the verb we'd like to send.

PS C:\> Invoke-RestMethod -Method Get -Uri 'https://jsonplaceholder.typicode.com/posts/1'
 
 userId id title                                                                      body
 ------ -- -----                                                                      ----
      1  1 sunt aut facere repellat provident occaecati excepturi optio reprehenderit quia et suscipit...

Notice that I was able to see what the first post looked like. I wanted to see the post with the id of 1, so I specified that in the URI. I could choose to remove the 1 completely and return all posts as well. This is standard practice with a REST API. By using the URI, you are limit the information that is retrieved making the URI an endpoint to connect to and a filter. We could also return all of the other objects from this demonstration API as well by just changing posts to photos, albums or whatever other objects this API exposes.

We also need to create objects. This is done with the POST verb. Other than using a different method, we'll also need to provide some way to send the data we need to create to the API. We do this by sending HTTP headers to the API's endpoint using the Headers parameter.

PS> Invoke-RestMethod -Method Post -Uri 'https://jsonplaceholder.typicode.com/posts' -Headers @{Title='testing123';body='testing'}
 
 id
 --
 101

You can see above that I was able to create a post and it was assigned the ID of 101. I was able to figure out what headers to pass from the output I received when using the GET verb.

Finally, we need to modify existing resources. To do that, we use the PUT verb. Because we're targeting an existing resource, we specify the resource by an ID of 1. Then, in the headers is where we can add the attributes to update.

PS > Invoke-RestMethod -Method Put -Uri 'https://jsonplaceholder.typicode.com/posts/1' -Headers @{ UserId=1;Title='testing1234';body='testing' }
 
 id
 --
 1

There's a lot more to working with REST APIs and PowerShell. Since each API is a little different, always be sure to reference the documentation first. Once you're comfortable with the schema that service uses, you'll find that every REST API is similar and can be communicated with using the examples you've seen above.