Developing PowerShell modules for REST APIs – Part1

Over the years I have developed different PowerShell modules for different web APIs. I thought it would be a good idea to write a 2 series post about how you could go about to do this. This will be a 2 part blog series where we will run through the entire process of building a module for a REST API. I will try my best to keep this as simple as possible and leave more advanced stuff for a follow up post if the interest is there.

What you need

Depending on your experience with source control and PowerShell in general, you might want to use GIT or some other software repro for the code. In addition we are going to create a test REST API using the splendid UniversalDashboard PowerShell module created by Adam Driscoll. It is available on the PowershellGallery. Other prerequisites are built-in to Powershell. I will assume that you will be following along using at least PowerShell version 5 or greater.

What is HTTP metods for REST API.

The primary or most common HTTP verbs used are POST, GET, PUT, PATCH and DELETE.

• POST - Create something
• GET - Read or get something
• PUT - Update or replace something
• PATCH - Update or modify something
• DELETE - Delete something

To keep it as simple as possible, I will focus on using POST and GET in this guide.

Authorization

APIs usually have some sort of requirement of authentication using a key. The UniversalDashboard module does not yet support authorization for REST endpoint, however we are going to fake it. My pseudo authentication method is not something you should ever use in production.

The REST API

We will create an API that enables you to list the files in a folder on your drive, sorry was the best I could come up with. The API will also let you create files with content. I know this is kind of not really exciting, however the overall goal is to keep it simple and everybody understands files.

REST Endpoints

First if you don’t have the UnversalDashboard module installed, fire up PowerShell and download the module from the Gallery:

    Install-Module -Name UniversalDashboard –Force

Now we are going to create our first GET endpoint.

	$GetFileEndpoint = New-UDEndpoint -Url "/file/" -Method "GET" -Endpoint {
	Param(
	$Authorization
	)
	if ($request.headers.ContainsKey("Authorization"))
	{
	$Authorization = $request.headers["Authorization"].ToString()
	}
	if ([string]::IsNullOrEmpty($Authorization))
	{
	throw "You shall not pass"
	}
	$secretBytes = [System.Convert]::FromBase64String(($Authorization -replace "Basic "))
	[string]$Secret = [System.Text.Encoding]::UTF8.GetString($secretBytes)
	$path = Join-Path -Path c: -ChildPath temp | Join-Path -ChildPath Api
	if ($Secret -eq 'foo:bar')
	{
	$output = foreach ($f in (Get-ChildItem -Path $path))
	{
	$fileObj = [pscustomobject]@{
	Name = $f.Name
	Size = $f.Length
	BaseName = $f.BaseName
	Extension = $f.Extension
	}
	$fileObj
	}
	$output | ConvertTo-Json
	}
	else
	{
	throw "You shall not pass"
	}
	}

view raw GetFileEndpoint.ps1 hosted with ❤ by GitHub

We create a New-UDEndpoint with the partial url of "/file/" and we will support the GET method. The endpoint it self is just a scriptblock that is executed in a separate runspace on your machine. Currently an GET Endpoint does not support parameters (Authorization) in the scriptblock like a POST endpoint does, however I included it anyway. You notice we have to extract the Authorization value from the request header from the runspace. The endpoint assumes that you have a folder ($path) on you computer with path "c:\temp\api". If the folder does not exists, you will have to create it. If the request contains the supersecret key "foo:bar" the request will get all the files in c:\temp\api and write them to the pipeline as JSON-object. If you do not understand the authorization key concept, do not worry, we will create an helper function, actually two helper functions, that will help you create the key.

Next up is our POST endpoint which is quite similar.

	$CreateFileEndpoint = New-UDEndpoint -Url "/file/" -Method "Post" -Endpoint {
	Param(
	$Authorization
	,
	$FileName
	,
	$Content
	)
	$secretBytes = [System.Convert]::FromBase64String(($Authorization -replace "Basic "))
	[string]$Secret = [System.Text.Encoding]::UTF8.GetString($secretBytes)
	$path = Join-Path -Path c: -ChildPath temp | Join-Path -ChildPath Api
	if ([string]::IsNullOrEmpty($Authorization))
	{
	throw "You shall not pass"
	}
	if ($Secret -eq 'foo:bar')
	{
	$fullPath = Join-Path -Path $path -ChildPath $FileName
	Set-Content -Path $fullPath -Value $Content
	$file = Get-ChildItem -Path $fullPath
	[pscustomobject]@{
	Name = $file.Name
	Size = $file.Length
	BaseName = $file.BaseName
	Extension = $file.Extension
	} | ConvertTo-Json
	}
	else
	{
	throw "You shall not pass"
	}
	}

view raw CreateFileEndpoint.ps1 hosted with ❤ by GitHub

The POST method supports scriptblock parameters, and we need Authorization, FileName and Content parameters to be able to create files. As you may notice, we have the same decoding of the Authorization key.

Helper functions

To aid us in working with the API, we need 2 helper functions to be able to create an Authorization key. Normally the key is added as an header to a request or in the actual body of the request. We will have to add the key to the body of the request for the POST endpoint.

	function Get-AuthorizationHeader
	{
	[cmdletbinding()]
	Param(
	[Parameter(
	ValueFromPipeline)]
	[PSCredential]
	$Credential
	)
	Begin
	{
	$f = $MyInvocation.InvocationName
	Write-Verbose -Message "$f - START"
	}
	Process
	{
	if (-not $Credential)
	{
	Write-Warning -Message "Credential parameter is null"
	return
	}
	$userName = $Credential.GetNetworkCredential().UserName
	$pass = $Credential.GetNetworkCredential().Password
	$domain = $Credential.GetNetworkCredential().Domain
	[string]$authString = "$($userName):$pass"
	if (-not [string]::IsNullOrEmpty($domain))
	{
	[string]$authString = "$($userName)@$($domain):$pass"
	}
	$auth = $authString | ConvertTo-Base64
	@{
	"Authorization" = "Basic $auth"
	}
	}
	End
	{
	Write-Verbose -Message "$f - END"
	}
	}
	function ConvertTo-Base64
	{
	[cmdletbinding()]
	Param(
	[Parameter(
	Mandatory,
	ValueFromPipeline)]
	[string[]]
	$InputObject
	)
	Begin
	{
	$f = $MyInvocation.InvocationName
	Write-Verbose -Message "$f - START"
	}
	Process
	{
	foreach ($string in $InputObject)
	{
	$bytes = [System.Text.Encoding]::UTF8.GetBytes($string)
	[System.Convert]::ToBase64String($bytes)
	}
	}
	End
	{
	Write-Verbose -Message "$f - EMD"
	}
	}

view raw HelperFunctions.ps1 hosted with ❤ by GitHub

The Get-AuthorizationHeader is the main function that will create the key for us. The ConvertTo-Base64 function is used by Get-AuthorizationHeader to encode the key.

First test

To make sure everything is working, we will test the GET Endpoint. Copy the helper functions and the endpoint definition to your favorite PowerShell editor. Then we will start the Endpoint and create an key that can authenticate us against the API:

	Start-UDRestApi -Port 11000 -Endpoint @($CreateFileEndpoint, $GetFileEndpoint)
	$securePwd = ConvertTo-SecureString -String bar -AsPlainText -Force
	$authKey = [PSCredential]::New("foo", $securePwd) | Get-AuthorizationHeader
	$invokeSplat = @{
	Uri = "http://localhost:11000/api/file"
	Method = 'Get'
	Headers = $authKey
	}
	Invoke-RestMethod @invokeSplat

view raw RegisterEndpoint.ps1 hosted with ❤ by GitHub

First we start the Endpoints by running Start-UDRestApi. You may get a firewall warning when you run the cmdlet. You have to allow traffic to the port you have selected for this to work. I selected post 11000 as the listening port for my API, however you may choose another port on your computer. Next we create a securestring containing our password "bar". Then we create a PSCredential object and pipe that to our helper function Get-AuthorizationHeader function. To test the Endpoint, we run the Invoke-RestMethod cmdlet and use the key just created. If everything work, you should have something like this in your window:



Those are the 3 files I have in my c:\temp\api folder.

That is it for part 1, In part 2 we will start to create a small PowerShell module and make it even more awesome. Stay tuned!

Cheers

Tore