Creating PowerShell RESTFul EndPoints

Yes, you can do this. No, its not ready for prime time……  yet! So what am I really talking about here? This is the beginning of creating very useful PowerShell applications on a modern application framework. It will allow you to use the same API calls to your PowerShell scripts that you might use with other services in your infrastructure.

Quick links:

• https://www.powershellgallery.com/packages/RestPS
• https://github.com/jpsider/RestPS

okay….  but WHY?

• Consistency
• Flexibility
• Versioning
• Scalability
• Ease of use
• Security (kinda, only expose Endpoints you want/need)

This is a great platform to develop a ‘PowerShell Application Server’ that you can access with other Powershell scripts and other services can now access the same information that your PowerShell scripts can generate.

Now, the Why nots…

• While its easy, its another layer.
• Security (no SSL yet)
• Memory (you MUST properly remove variables, and garbage collect!)
• No SwaggerUI (hopefully you know what this is!)

So lets Dive in with a basic use case of getting some process information off of the OS.

First, just install the module from the PowerShell Gallery:

Install-Module -Name RestPS

There is only one exported function ‘Start-RestPSListener’ which requires no parameters. I do suggest you use them!

• -Port (default is 8080)
• -RoutesFilePath (Default uses the built in Routes which is not recommended!)

You can copy the file ‘Invoke-AvailableRouteSet.ps1’ to ‘c:\temp’ and specify this as your Routes file path. (I also recommend adding ‘Invoke-AvailableRouteSet’ as the last line of this file). This will allow you to reload the routes with each REST API call to your server.

Now, your first endpoint can be started up like this:

Import-Module -Name RestPS

Start-RestPSListener -Port 8081-RoutesFilePath "c:\temp\Invoke-AvailableRouteSet.ps1"

From a second console you can now run web requests to this new Endpoint.

Invoke-RestMethod -Method Get -Uri "http://localhost:8081/proc"

Invoke-RestMethod -Method Get -Uri "http://localhost:8081/process?vmware-tray"

It’s that simple! The Web listener will execute any command or script defined in your Routes file. If the Route is unknown a message will be sent back ‘Invalid Command’.

To shut the Endpoint down, send the following comand:

Invoke-RestMethod -Method Get -Uri "http://localhost:8081/Endpoint/Shutdown"

Below is an image of the Calls from each console.

You can see this is a very easy project to get started with. You can now put a pretty simple web front end on any of your scripts. Give access to outside users to run your scripts. Just use some caution! You only have to expose endpoints/scripts you want folks to have access to. I have not started the road down SSL yet.

Check it out, have some fun, give some feedback!

Reference projects:

https://github.com/cofonseca/WebListener?files=1

http://hkeylocalmachine.com/?p=518