Endpoints
Endpoint configuration for Universal APIs.
Last updated
Endpoint configuration for Universal APIs.
Last updated
Endpoints are defined by their URI and HTTP method. Calls made to the Universal server that match your defined API endpoint and method execute the API endpoint script.
To invoke the above method, you can use Invoke-RestMethod
.
When defining endpoints in the management API, you can skip the New-PSUEndpoint
call, as the admin console defines it.
The only contents that you need to provide in the editor are the script you wish to call.
Avoid using endpoint URLs that match internal PowerShell Universal Management API URLs, as this causes unexpected behavior. You can reference the OpenAPI documentation for the Management API to verify that none of the URLs match.
Endpoints can have one or more HTTP methods defined. To determine which method is used by an endpoint, use the built-in $Method
variable.
URLs can contain variable segments. You can denote a variable segment using a colon (:
). For example, the following URL would provide a variable for the ID of the user. The $Id
variable will be defined within the endpoint when it is executed. Variables must be unique in the same endpoint URL.
To call this API and specify the ID, do the following:
Query string parameters are automatically passed into endpoints as variables that you can then access. For example, if you have an endpoint that expects an $Id
variable, you can provide it in the query string.
The resulting Invoke-RestMethod
call must then include the query string parameter.
When accepting input via Query String parameters you may be vulnerable to CWE-914: Improper Control of Dynamically-Identified Variables. Consider using a param
block to ensure that only valid parameters are provided to the endpoint.
Below is an example of CWE-914. Include a $IsChallengePassed
query string parameter to bypass the challenge.
In order to avoid this particular issue, you can use a param
block.
Request headers are available in APIs using the $Headers
variable. The variable is a hashtable. To access a header, use the following syntax:
Request cookies are available in APIs using the $Cookies
variable. The variable is a hashtable. To access a cookie, use the following syntax:
Send back request cookies with the New-PSUApiResponse
cmdlet. Use the -Cookies
parameter with a supplied hashtable.
To access a request body, you will simply access the $Body
variable. Universal $Body
variable will be a string. If you expect JSON, you should use ConvertFrom-Json
.
To call the above endpoint, specify the body of Invoke-RestMethod
.
You can view the live log information for any endpoint by clicking the log tab. Live logs include URL, HTTP method, source IP address, PowerShell streams, status code, return Content Type, and HTTP content length.
You can pass data to an endpoint as form data. Form data will pass into your endpoint as parameters.
You can then use a hashtable with Invoke-RestMethod to pass form data.
You can pass JSON data to an endpoint and it will automatically bind to a param block.
You can then send JSON data to the endpoint.
You can use a param
block within your script to enforce mandatory parameters and provide default values for optional parameters such as query string parameters. Variables such as $Body
, $Headers
and $User
are provided automatically.
In the below example, the $Name
parameter is mandatory and the $Role
parameter has a default value of Default.
When using the param
block with route parameters like the above example, you must include the route variable in your parameter. If it is not specified, you will not have access to that value.
For example, the following $Name
variable is always $null
. The endpoint always returns false.
Data returned from endpoints is assumed to be JSON data. If you return an object from the endpoint script block, it is automatically serialized to JSON. If you want to return another type of data, you can return a string formatted however you chose.
You can process uploaded files by using the $Data
parameter to access the byte array of data uploaded to the endpoint.
The multipart/form-data
content type is not supported for uploading files to APIs.
You can also save the file into a directory.
You can send files down using the New-PSUApiResponse
cmdlet.
You can return custom responses from endpoints by using the New-PSUApiResponse
cmdlet in your endpoint. This cmdlet allows you to set the status code, content type and even specify the byte[] data for the content to be returned.
You can also return custom body data with the -Body
parameter of New-PSUApiResponse
.
Invoking the REST method returns the custom error code.
You can control the content type of the returned data with the -ContentType
parameter.
Persistent runspaces allow you to maintain runspace state between API calls. This is important for users that perform some sort of initialization within their endpoints that they do not want to execute on subsequent API calls.
By default, runspaces are reset after each execution. This removes variables, modules and functions defined during the execution of the API.
To enable persistent runspaces, you will need to configure an environment for your API. Set the -PersistentRunspace
parameter to enable this feature. This is configured in the environments.ps1
script.
You can then assign the API environment in the settings.ps1
script.
By default, endpoints will not time out. To set a timeout for your endpoints, you can use the New-PSUEndpoint
-Timeout
parameter. The timeout is set in the number of seconds.
You can define the path to an external endpoint content file with the -Path
parameter of New-PSUEndpoint
. The path is relative to the .universal
directory in Repository.
The content of the endpoints.ps1
file is then this:
C# APIs are enabled as a plugin.
There is no UI for creating a C# API, so you need to do so using configuration files. First, create a .cs
file that runs your API.
You will have access to a request
parameter that includes all the data about the API request.
You will also have access to a ServiceProvider
property that allows you to access services within PowerShell Universal. These are not currently well-documented, but below is an example of restarting a dashboard.
Some other useful services include:
IDatabase
IApiService
IConfigurationService
IJobService
You can choose to return an ApiResponse
from your endpoint.
Once you have defined your C# endpoint file, you can add it by editing endpoints.ps1
.
The PowerShell Universal service automatically compiles and runs C# endpoints.