REST APIs
Universal Dashboard is now a part of PowerShell Universal. This documentation is for reference to the v2 version of Universal Dashboard and is no longer maintained.
REST APIs
Using the same web hosting platform as the rest of Universal Dashboard, you can create REST APIs that have no user interface component. You can accept input from the user from URLs and HTTP request bodies and accept four different HTTP methods.
Creating new endpoints
To create a new endpoint, you will use the New-UDEndpoint cmdlet. This cmdlet lets you specify the URL, the HTTP method and the Endpoint Script Block that will process the data.
To create a simple endpoint to return data, you can create an with the following script.
1
$Endpoint = New-UDEndpoint -Url "/process" -Method "GET" -Endpoint {
2
Get-Process | ForEach-Object { [PSCustomObject]@{ Name = $_.Name; ID=$_.ID} } | ConvertTo-Json
3
}
4
Start-UDRestApi -Endpoint $Endpoint
Copied!
This endpoint could be invoked with Invoke-RestMethod like so. Notice that all URLs are prefixed with "api".
1
Invoke-RestMethod -Uri http://localhost:80/api/process
Copied!
Endpoints with variables in the URL
In REST, resources are identified by the variables in the path of the URL. Universal Dashboard, supports variables by specifying a colon (:) in the URL path. These variables are then passed to the script block of the endpoint.
For example, if you wanted to get a process by ID, you could specify the ID variable in the URL and add a $ID parameter to the param block of the Endpoint script block.
1
New-UDEndpoint -Url "/process/:id" -Method "GET" -Endpoint {
2
param($Id)
3
​
4
Get-Process -Id $Id | ForEach-Object { [PSCustomObject]@{ Name = $_.Name; ID=$_.ID} } | ConvertTo-Json
5
}
Copied!
Using RegEx in Endpoint URLs
Instead of simple variables, you can instead use RegEx expressions to match URL patterns. This is handy for integration with systems like the DSC PullServer that provides complex URL patterns. Named groups will be passed to the endpoint as parameters. You'll need to include the
-EvaluateUrlAsRegex parameter to New-UDEndpoint.1
$Endpoint = New-UDEndpoint -Url "nodes\(AgentId=(?<AgentId>[0-9]*)\)" -Method "PUT" -Endpoint {
2
param($AgentId)
3
​
4
$AgentId | ConvertTo-Json
5
} -EvaluateUrlAsRegex
6
​
7
Start-UDRestApi -Endpoint $Endpoint -Force
8
​
9
Invoke-RestMethod -Uri 'http://localhost:80/api/nodes(AgentId=1234)' -Method PUT
Copied!
Endpoints that take data from the HTTP request body
HTTP methods like POST take data from the request body. UD supports form data and string data. Form data will automatically be parsed and provided to the script block via parameters.
1
$Endpoint = New-UDEndpoint -Url "/process" -Method "POST" -Endpoint {
2
param($FilePath, $Arguments)
3
​
4
Start-Process -FilePath $FilePath -ArgumentsList $Arguments
5
}
6
Start-UDRestApi -Endpoint $Endpoint
7
​
8
Invoke-RestMethod -Uri http://localhost:80/api/process -Method POST -Body @{FilePath = "code"; Arguments = "script.ps1" }
Copied!
Additionally, you can specify any string value and that value will be provided to the script block via the Body parameter.
1
$Endpoint = New-UDEndpoint -Url "/process" -Method "POST" -Endpoint {
2
param($Body)
3
​
4
$Parameters = $Body | ConvertFrom-Json
5
​
6
Start-Process -FilePath $Parameters.FilePath -Arguments $Parameters.Arguments
7
}
8
Start-UDRestApi -Endpoint $Endpoint
9
​
10
Invoke-RestMethod -Uri http://localhost:80/api/process -Method POST -Body (@{FilePath = "code"; Arguments = "script.ps1" } | ConvertTo-Json)
Copied!
Managing the REST API Servers
Endpoints will need to be passed to Start-UDRestApi to create a new REST API server. Start-UDRestApi has all the same hosting options as Start-UDDashboard. It supports HTTPS and can be hosted in Azure and IIS.
1
Start-UDRestApi -Port 80 -Endpoint $MyEndpoints
Copied!
Just as with Get-UDDashboard and Stop-UDDashboard, you can locate and stop any running dashboards with Get-UDRestApi and Stop-UDRestApi.
1
Get-UDRestApi -Name "ProcessApi" | Stop-UDRestApi
Copied!
You can also add REST API endpoints to existing dashboards with the Endpoint parameter of Start-UDDashboard. This allows you to have a user interface for your dashboard but also provide REST API endpoints on the same port.
1
Start-UDDashboard -Endpoint $MyEndpoints -Dashboard $MyDashboard
Copied!
Returning XML
By default, REST API endpoints set the Content-Type HTTP header to application/json. Any web-client consuming your endpoint will assume the content returned is formatted as JSON. In order to return content as XML, you can use the Set-UDContentType cmdlet to set the content type to application/xml.
1
New-UDEndpoint -Url "project" -Method "GET" -Endpoint {
2
Set-UDContentType "application/xml"
3
​
4
"<Project name=`"test`"></Project>"
5
}
Copied!
If you would like to support both JSON and XML in the same endpoint, you can also use Get-UDContentType to get the requested content type.
1
New-UDEndpoint -Url "project" -Method "GET" -Endpoint {
2
$ContentType = Get-UDContentType
3
if ($ContentType -eq "application/json") {
4
"{Project:{name:'test'}}"
5
} else {
6
Set-UDContentType "application/xml"
7
"<Project name=`"test`"></Project>"
8
}
9
}
Copied!
Uploading Files
REST APIs support uploading files. You need to enable file uploads via the
New-UDEndpoint cmdlet. Be careful when accepting files as it can pose a security risk. The file is provided to an endpoint as an array of bytes that you can then output and process how ever you like. You should accept a $File parameter to gain access to the upload byte array.In this example, we upload a file and save it to disk using
Set-Content.Note: file upload is only avaliable using contenttype
file/* or image/* where * is a wildcard. The original filename is not transfered, and the wildcard is the only metadata avaliable other than the bytearray.1
New-UDEndpoint -Url "project" -Method "POST" -AcceptFileUpload -Endpoint {
2
param($File)
3
$filepath = "C:\temp\"
4
$filename = New-Item -Path $filepath -Name "$(get-random).txt"
5
​
6
if (!($File)) {
7
throw "file is empty."
8
}
9
​
10
Set-Content -Path $filename -Value $File -Encoding Byte
11
}
Copied!
Last modified 3mo ago