One Tool, All APIs: API Parameters with PowerShell

This is the third post in the One Tool, All APIs: PowerShell series. Previous posts:

1. One Tool, All APIs: PowerShell As The All-Purpose API Client
2. One Tool, All APIs: API Authentication With PowerShell

Today we are going to dive into API Parameters with PowerShell.

So, let’s get clear about what actually API parameters are. They are the variables that you include in the API request to provide additional information to the API.

There are 2 API Parameter types, Query Parameters and Request Body Parameters.

Query Parameters are appended to the end of the URL in a GET request. Used to filter, limit, or modify the data returned.

Request Body Parameters are included in the body of the request, typically used in POST or PUT requests. Used to provide data for the API to process.

There are no universal standards specifically for API parameters. Typically, they are defined by the API developers or protocol being used. The common denominator is the adherence to RESTful principles and HTTP conventions.

However, several RFCs cover related topics, such as URI syntax, HTTP methods, and query strings.

• RFC 3986 – defines URI syntax, including query components in a URL
• RFC 7230,7231 – specify how HTTP messages, including requests with parameters, should be structured
• RFC 6570 – introduces URI Template syntax, which some APIs use for specifying resource URIs with variables

In our small made-up world, we have PowerShell with Invoke-WebRequest and Invoke-RESTMethod cmdlets. Let’s see how you can pass different API parameters using them.

API Query Parameters with PowerShell

As we already discussed, query parameters are part of the URL itself. So, our main task is to craft URL with the needed parameters and values.

Because not all of the parameters are required (some of them are optional), we need to think about the convenience and usability. Obviously, user can manually create the query string and then send the request to the API endpoint. When there is only one parameter, we can use simple variable to substitute the value in the URL string. This will be very straightforward and not fun. So, to make it more flexible we can have a generic function that will transform parameters and their values into the query, and we will just append it to the Base URL.

In pseudo code it will look something like this:

Input parameters and their values (probably via hash table)
Compile key and value pairs into query string 
Output query string that can be appended to URL

We can wrap it up in a simple quick & dirty function for convenience:

function New-APIParameters {
    [CmdletBinding(SupportsShouldProcess=$true)]
    param (
      [hashtable]$Parameters  
    )
    begin {}
    process {
        if ($pscmdlet.ShouldProcess("$Parameters"))
        {
            $query="?"
            foreach ($i in $p.Keys){
                $query+="$i=$($p[$i])&"
            }
            $query=$query.Substring(0,$($query.Length-1))
            $query
        }
    }
    end {}
}

In terms of usage, it will be pretty much the same with both cmdlets. Let’s look into the examples.

In first example our API have only 1 required parameter, so the usage of our function will not yield a lot of benefits:

$domain="example.com"
$url="https://isbehindcdn.p.rapidapi.com/isbehindcdn?domainname=$domain"

Invoke-WebRequest -Uri $url -Headers $headers

Invoke-RestMethod -Uri $url -Headers $headers

Get more information about IsBehindCDN API.

In the next example the endpoint have multiple parameters and our function will be very handy.

$Url="https://commonportnumbers.p.rapidapi.com/commonportnames"
$APIParams=@{
   port="53"
   protocol="tcp"
}
$query=New-APIParameters -Parameters $APIParams
Invoke-RestMethod -Uri $($url+$query) -Headers $headers

Get more information about CommonPortNumbers API.

API Request Body Parameters with PowerShell

Request Body parameters are passed as a payload via Body of the request. We can simply pass the hash table and cmdlet will do the work for us.

Moreover, both of the cmdlets are capable of automatic transformation of the passed parameters based on the HTTP request. Meaning that cmdlets are smart enough to figure out where actually to append the parameters that you are throwing at it.

Conclusion

Although our little experiment with the function that transforms hashtable into URL was fun and interesting, it was completely unnecessary. Out of the box cmdlets (Invoke-WebRequest & Invoke-RESTMethod) are designed and accounted for all possible API parameters and ways to pass them.

Main lesson learned – RTFM is the key.

Next: Construct API Headers with PowerShell

Icons created by Freepik – Flaticon.

Thanks a lot for reading.