Tips and Tricks

This section provides advice that will make your experience with the REST API smoother and easier.

Run as Administrator When on the Console

If you are connecting to the REST API on the Security Controls console, you must run PowerShell with Run as Administrator privileges. This is not required if you are connecting remotely from another machine.

Create a Hash Table for the REST API URIs

It is a good coding practice to put all of the REST API URIs in a hash table and then reference the hash table within your queries. This way, if something changes with the formatting or if new URIs are added, all of the URIs are located in one place and are easy to update.

Session Credential

A session credential is required if you need to set user credentials or access stored credentials from within a REST API call.

Session credentials are not required if you are running as administrator on the Security Controls console.

Invoke-WebRequest vs Invoke-RestMethod

Both cmdlets can be used to initiate REST API calls, but Invoke-WebRequest returns an additional Operation-Location header that is not provided when using Invoke-RestMethod. The Operation-Location header information is beneficial when initiating a patch scan or a patch deployment because it enables you to wait for the scan or deployment to complete.

Links Within Output

Most REST API calls contain links as part of the return code. These links are already properly structured and can be very handy for making your next REST API call.

Paginated Results

By default, most REST API requests will return only 10 items at a time. A function named Get-PaginatedResults can be used to automatically loop through and retrieve all items. To view a sample implementation of this function, see Start-to-Finish Example Using PowerShell.

Error Handling and Testing

Make sure your scripts properly handle all error conditions and scenarios.

Patch Cycles

It is a best practice to use a patch group when testing and deploying patches. If you use the results of patch scan template when performing a deployment, it is possible for new patches to be released between the start of your testing cycle and your release cycle and you may unintentionally deploy untested patches into your live environment.

PowerShell Modules

Put your generic functions into PowerShell modules. This way, they can be easily using in multiple patch automation scripts and they are centralized for easy updating.