Create your first basic API in PowerShell using Pode

In this post I will cover my first experiences using Pode to create my own basic API. Pode is a Cross-Platform PowerShell framework for creating web servers to host REST APIs, Web Sites, and TCP/SMTP Servers.

For this post I will use Pode on MacOS with PowerShell Core 6.2 and I’ve used the official Pode documentation to create these examples.

Install Pode

• Install Pode from the PowerShell Gallery using the Import-Module and Install-Module command.
• There are also Docker images available.
• When you use Chocolatey, just type choco install pode.

For this article I used PowerShell Gallery to install Pode.

Setup your first Pode project

Each project you’re going to create needs to have some basic configuration and files. We can create those by following a few simple steps.

• First, create a folder on the local machine where files of this project are going to be placed in. In my case I’m going to give it the name: pode. Full path of my project will be /Users/bjorn/github/pode.
• Navigate to this directory using PowerShell and type pode init. This will initiate the basic information of your project. You can enter any information that you like.

PS> pode init
name (my-first-pode-app):
version (1.0.0):
description:
entry point (./server.ps1):
author:
license (MIT):
Success, saved package.json

• Next, create a file called server.ps1 in the root directory of your project.

Server script

• Using your favourite script editor, open the server.ps1 in the project folder you’ve just created.
• Define the first block in the script, in here you will define all the logic that is needed to configure te server, and how it should function.

#Start Pode Server
Start-PodeServer {
    #All your commands and logic should be inside these brackets
}

• To make the Pode server listen to incoming request and respond to them, we need to create an endpoint. We use localhost as the address for now, make it listen on port 8000 and use HTTP as protocol.

#Start Pode Server
Start-PodeServer {

    #Attach port 8000 to the local machine address and use HTTP protocol
    Add-PodeEndpoint -Address localhost -Port 8000 -Protocol HTTP
}

• Next up, we will start to add a new route in the form of a GET method. It will be invoked when the path of the route is called (http://localhost:8000/static). In this case the route responds a static value offered in the JSON format.

#Start Pode Server
Start-PodeServer {

    #Attach port 8000 to the local machine address and use HTTP protocol
    Add-PodeEndpoint -Address localhost -Port 8000 -Protocol HTTP

    #Create route and return a static value
    Add-PodeRoute -Method Get -Path '/static' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'value' = 'My first API response!' }
    }
}

Tip: Other responses (CSV, HTML, File and XML) are also available.

• Save the server.ps1 file and start the server by typing pode start or call the file in the directory ./server.ps1.
• Start a new PowerShell console on your machine and use Invoke-RestMethod to send a request to our API.

Invoke-RestMethod -Method GET -Uri http://localhost:8000/static 

Return dynamic responses

In the first example we’ve created a JSON response that always returns the same value. Now, we’re going to setup a basic example on how you can use PowerShell to retrieve data and parse it into a JSON value.

• Add een second route in your script in the form of a GET method. This time, create the path and name it /dynamic.
• In this example I am going to use the Get-Random command to give me a number between 1 and 30.
• Because the command outputs the number as a string, we need to store it in an object to pipe it to ConvertTo-JSON. Doing this will give us the number as a JSON value, which we can use in our new route.

#Create route and give a random number as response
    Add-PodeRoute -Method Get -Path '/dynamic' -ScriptBlock {           
        
        #Generate random number and store it into a custom object
        $random = Get-Random -Minimum 1 -Maximum 30
        $object = New-Object -TypeName PSCustomObject
        $object | Add-Member -MemberType NoteProperty -Name Number -Value $random
        
        #Get the custom object and convert it to JSON
        $response = $object | ConvertTo-Json 
        Write-PodeJsonResponse -Value $response
    }

• Save the server.ps1 once again and start the server.
• In your secondary PowerShell console, use Invoke-RestMethod to send a request to our API.

Invoke-RestMethod -Method GET -Uri http://localhost:8000/dynamic

Full server.ps1 file

#Start Pode Server
Start-PodeServer {

    #Attach port 8000 to the local machine address and use HTTP protocol
    Add-PodeEndpoint -Address localhost -Port 8000 -Protocol HTTP

    #Create route and return a static value
    Add-PodeRoute -Method Get -Path '/static' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ 'value' = 'My first API response!' }
    }

    #Create route and give a random number as response
    Add-PodeRoute -Method Get -Path '/dynamic' -ScriptBlock {           
        
        #Generate random number and store it into a custom object
        $random = Get-Random -Minimum 1 -Maximum 30
        $object = New-Object -TypeName PSCustomObject
        $object | Add-Member -MemberType NoteProperty -Name Number -Value $random
        
        #Get the custom object and convert it to JSON
        $response = $object | ConvertTo-Json 
        Write-PodeJsonResponse -Value $response
    }
}

Wrapping things up

With Pode it is very easy to build a custom API in PowerShell. If you know how to work with PowerShell, you know how to work with Pode. You have seen how you create your first project and add routes to create a functional REST API.

Now it’s time to make it scalable by exploring automatic adding of routes, creating some basic API authorization and starting the server as a service on your machine.

What are you struggling with or what ideas do you have for Pode? Please leave a comment below or send me a message on Twitter!