This guide will cover how to build REST APIs using Universal Dashboard and PowerShell. Most of this post can be accomplished with Universal Dashboard Community. Only the section covering Authentication and Authorization will require Premium or Enterprise.
What is a REST API?
Representational state transfer (REST) is a software architecture that defines how web services should be designed. In practice, it takes advantage of the HTTP verbs to dictate which actions are requested by the client and uses the URL and query string to identify which resources are being acted upon.
For example, you may have an API that provides access to users that can be addressed by the URL /api/user. You can then perform different operations on the users based on the HTTP verb. A GET request would return users. A POST request would create a new user. A DELETE request would remove a user.
REST APIs are very popular and you are probably using them already; even if you don’t realize it.
REST APIs with PowerShell
To create simple endpoints with PowerShell, we will use the New-UDEndpoint cmdlet and specify a URL as well as a verb. Below you’ll find all the recipes for creating REST APIs with various options.
This section will cover ways to access various information about HTTP requests. All of these techniques can be used with any HTTP verb.
Assume we have a collection of users as follows.
You can specify parameters by including a URL segment that starts with a colon (:).
Multiple route parameters
You can specify multiple route parameters.
Universal Dashboard will set parameters based on the query string as well as route parameters.
The $Request variable has all the information about the HTTP request. You can access headers view the Headers property of the $Request object.
You can also specify a regular expression within your route. You can use named groups to retrieve parameters that are part of the regular expression.
This section will cover how to expose endpoints that implement various HTTP verbs.
The GET verb is used for returning data to the client. It should not modify state.
The POST verb is used for creating a new entity based on the data specified by the client.
The PUT verb is used for updating an existing entity.
The DELETE verb is used for deleting an existing entity.
You can upload files via a Universal Dashboard REST API by specifying the -AcceptFileUpload parameter on New-UDEndpoint. The file contents will be available as a byte array in the $File parameter.
You can return data of other content types, such as XML, by using the Set-UDContentType cmdlet before returning your data from within your endpoint.
Authentication requires Universal Dashboard Premium or Enterprise.
You can use JSON Web Tokens and basic authentication when using a UD REST API. You can choose to return a JWT token from your basic authentication so that users can access the API without having to provide their user name and password again.
Authorization requires Universal Dashboard Premium or Enterprise.
You can provide roles to users so that only particular users can access particular endpoints. When a user logs in, you can specify the roles they are provided within their JSON web token. On the endpoints, you can use the AuthorizedRole parameter to specify which roles have access to the endpoint.
Authorization policies allow you to execute PowerShell script against an identity and determine whether or not they have access to a particular REST API. You can provide additional claim information by passing a hashtable to the -Payload parameter for Grant-UDJsonWebToken.