Endpoints
Endpoint configuration for Universal APIs.
Endpoints are defined by their URI and HTTP method. Calls made to the Universal server that match the API endpoint and method that you define will execute the API endpoint script.
To invoke the above method, you could use Invoke-RestMethod
.
When defining endpoints in the management API, you can skip the New-PSUEndpoint
call as it will be defined by the admin console.
The only contents that you need to provide in the editor will be the script you wish to call.
Be aware that you should avoid using endpoint URLs that match with internal PowerShell Universal Management API URLs as this will cause unexpected behavior. You can reference the OpenAPI documentation for the Management API to verify this is not the case.
HTTP Methods
Endpoints can have one or more HTTP methods defined. To determine which method is used by an endpoint, use the built-in $Method
variable.
Variable URL
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, you would do the following.
Query String Parameters
Query string parameters are automatically passed into endpoints as variables that you can then access. For example, if you had an endpoint that expected an $Id
variable, it could be provided via the query string.
The resulting Invoke-RestMethod
call must then include the query string parameter.
Security Considerations
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. A $IsChallengePassed
query string parameter could be included to bypass the challenge.
In order to avoid this particular issue, you can use a param
block.
Headers
Request headers are available in APIs using the $Headers
variable. The variable is a hashtable. To access a header, use the following syntax.
Cookies
Request cookies are availablein APIs using the $Cookies
variable. The variable is a hashtable. To access a cookie, use the following syntax.
Request cookies can be sent back using the New-PSUApiResponse
cmdlet. Use the -Cookies
parameter with a supplied hashtable.
Body
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, you would have to specify the body of Invoke-RestMethod
.
Live Log
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.
Form Data
You can pass data to an endpoint as form data. Form data will be passed into your endpoint as parameters.
You can then use a hashtable with Invoke-RestMethod to pass form data.
JSON 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.
Param Block
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.
Returning Data
Data returned from endpoints will be assumed to be JSON data. If you return an object from the endpoint script block, it will be automatically serialized to JSON. If you want to return another type of data, you can return a string formatted however you chose.
Processing Files
Uploading Files
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 could also save the file into a directory.
Downloading Files
You can send files down using the New-PSUApiResponse
cmdlet.
Returning Custom Responses
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 by using the -Body
parameter of New-PSUApiResponse
.
Invoking the REST method will return the custom error code.
You can control the content type of the data that is returned by using the -ContentType
parameter.
Persistent Runspaces
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 will be reset after each execution. This will cause variables, modules and functions defined during the execution of the API to be removed.
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.
Timeout
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.
External Endpoint Content
You can define the path to an external endpoint content file by using 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
C# APIs are enabled as a plugin.
There is no UI for creating a C# API and you will need to do so using configuration files. First, you will need to create a .cs
file that will run 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 will allow you to access services within PowerShell Universal. These are currently not well documented but below is an example of restarting a dashboard.
Some other useful services may 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
.
C# endpoints are compiled and run directly in the PowerShell Universal service.
API
Last updated