Quickly Test APIs in PowerShell Pt2

Ah, so you’re back for more, eh? Couldn’t get enough the first time? You’re a glutton for punishment? Or maybe you’re just one of those weirdos who likes to read the end of the book first and skipped Part 1 of this series. If this is you, go get help. In part 2, we’re going to continue working with APIs in PowerShell by transforming our previous script into a function. Conjunction junction…what’s yo func…just imagine me singing this and I’ll imagine you begging me to make it stop.

\\\Disfunction Dis

Okay, so our previous script works and allows us to switch to various endpoints with just a few variables. We tested connecting to our Goodreads account so we could pull book and author info. First, let’s go over a few basic parts of a PowerShell function and the idea of how we’ll use it to make our life easier. If you’re unfamiliar with functions, think of it like wrapping your script or a portion of your script so you can one line that dude again and again. We can get wayyyy off track talking about how amazing advanced functions are and how they can lower your cholesterol and extend your vehicle warranty. But for now, I want to introduce you to a couple of techniques we’ll use specifically in this function.

–Positing the position

For each parameter in our function, we have parameter options that can give us more control over our parameters. One of these is the Position. Without any other settings defined, it would look like this:

[Parameter(Position=0)]
$Parameter}

If you’ve ever taken advantage of the Get-ADUser cmdlet and did something like this:

Get-ADUser lskywalker

Instead of this:

Get-ADUser -Identity lskywalker

This is possible because the -Identity parameter is defined as Position=0. It allows the first value to be assigned to the -Identity parameter even if it wasn’t referenced by name. Very cool. I’m not sure about you, but I like typing less and thereby narrowing the tunnel for carpal tunnel.

–Validate Me

Our next technique is the ValidateSet parameter option and this little beauty will give you more validation than your sweet Aunt Petunia did when you were a kid. Since our previous script included a switch statement, we can easily restrict a parameter to a series of values and use tab completion in our function. This looks like this:

[ValidateSet('User','Author','BooksByAuthor','Book')]
$Parameter

This is helpful if you’re giving this function to somebody else or if you don’t have total recall and you’ve slept since the last time your ran this function.

–Heard It Through the Pipeline

How much longerrrr will you be mine! Oh, sorry. Lastly, we’re going to work that pipeline to our advantage. This is something I didn’t take advantage of until far later in my scripting adventure. It would have really come in handy if I would have learned it sooner. This parameter option looks like this:

[Parameter(ValueFromPipeline=$true)]<br />$Parameter

There’s a lot of information on the various pipelines that PowerShell uses to pass information along, but for now let’s just talk about what this setting does. If you’ve ever piped one cmdlet to another, you’re essentially using the output of one function as the input for another function. Here’s an example from Exchange:

Get-Mailbox | Get-MailboxStatistics | Select TotalItemSize

We’re getting mailboxes using Get-Mailbox, then we’re piping the results to the Get-MailboxStatistics cmdlet before finally piping to the select (alias for Select-Object) to choose the TotalItemSize property. As handy as this ability is, our function can do the same and accept a value from the pipeline for a specific parameter.

\\\How bad is it, doc?

I know it seems like more work, but this function is going to make working with APIs in PowerShell easy peasy. Let’s look at how our function is coming together so far before getting into the nuts and bolts.

function API-Quickie{
    [CmdletBinding()]
    Param(
        # Param1 help description
        [Parameter(Mandatory=$true,Position=0)]
        [ValidateSet('User','Author','BooksByAuthor','Book')]
        $Endpoint,
        # Criteria for the endpoint (usually the id of the object or name to query)
        [Parameter(ValueFromPipeline=$true)]
        $Criteria
    )
    Begin{
        $Key = 'XXXXXXXXXXXXXXXX'
        $KeyString = "key=$Key"
        $BaseURL = 'https://www.goodreads.com/'
    }
    Process{
    }
    End{
    }
}

It’s ugly and doesn’t do much right now, but it’s our ugly and we’re proud of the little critter. In Part 1 we went over the Switch Statement that allowed us to easily switch between endpoints. One part we’re going to add to is for the BooksByAuthor endpoint. I didn’t want to overcomplicate Part 1 but the Goodreads API only returns 30 books at a time. I made a mistake and tested with Steven King and found a whopping 1764 books by The King. Dang. At 30 books a call, we have to make 59 calls to get all of the books! That’s a tough……….call………? Sorry, somebody let me out of the Dad Cave…

\\\Overachieving Authors

So for this next section I want to expound on it and explain what I’m doing. In a nutshell, we have to dynamically determine how many books there are and how many calls need to be made. If the author has less than 30 books, we only need to make one call, preferably not to Liam Neeson. If the author has more than 30 books, we need to determine how many and keep calling like a Karen who ordered the new chicken sandwich from McDonald’s and was sorely disappointed. But not too many times…just enough times to make sure the manager gets the point.

To do this, the Goodreads payload contains author.books.end (last book returned in this call) and author.books.total (total of number of books by the author). We use an empty array so we can keep adding all of our books (30 at a time). We also use a $PageNumber variable that we’ll increment using ++. And finally, we’re utilizing a Do Until Statement so we’ll keep getting results until we reach our last page.

All of that together looks like this:

To help visualize all of the if’s and else’s going on here, I’ve created this hand-drawn diagram on papyrus for you:

Final Destination

Finally, fate has brought us to our conclusion and we can look back at our work with great fondness. Here’s the finished function:

So what good is writing a function without making sure it can function? Let’s look at why we did all of that fancy parameter fun in the beginning of this post. Since our $Endpoint parameter has Position 0, we can go ahead and save ourselves the agonizing pain of typing 9 extra characters. And since our $Criteria parameter accepts a value from the pipeline, we can live out our pipedream and just pipe everything everywhere like the Rowdy Roddy Piper.

Here’s an example of how we could search an author by name, and then use the Author ID and pipe it to search for books by that author.

(API-Quickie Author -Criteria 'Ernest Cline').author.id | API-Quickie BooksByAuthor

And now you’ve gone from just working with APIs in PowerShell to a-whole-nother dimension with your own function. Can you feel that power in your shell?