functions/Invoke-RestApi.ps1

function Invoke-RestApi {
    <#
    .SYNOPSIS
    Invokes the Secret Server Rest API
 
    .DESCRIPTION
    Invokes the Thycotic Secret Server REST API
 
    .EXAMPLE
    $session = New-TssSession -SecretServer https://alpha -Credential $ssCred
    Invoke-TssRestApi -Uri 'https://vault.company.com/SecretServer/api/v1/secrets -PersonalAccessToken $session.AccessToken
 
    Performs request to the URI specified, returning all secrets the current credential has access to view (minimum).
 
    .EXAMPLE
    $session = tssnts https://alpha $ssCred
    tssira "$($session.ApiUrl)/secrets" $session.AccessToken
 
    Performs request to the URI specified, returning all secrets the current credential has access to view (minimum) using alias names for each function.
 
    .LINK
    https://thycotic-ps.github.io/thycotic.secretserver/commands/Invoke-TssRestApi
 
    .LINK
    https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/Invoke-RestApi.ps1
 
    .NOTES
    More detailed examples: https://thycotic-ps.github.io/thycotic.secretserver/docs/invoke-tssrestapi/
    #>

    [Cmdletbinding()]
    param(
        # Secret Server REST API URL
        [Parameter(Mandatory, ValueFromPipelineByPropertyName, Position = 0)]
        [Alias('Url')]
        [uri]
        $Uri,

        # Valid Access Token issued by Secret Server
        [Parameter(ValueFromPipelineByPropertyName, Position = 1)]
        [Alias('PAT')]
        [string]
        $PersonalAccessToken,

        # Method used for the web request, supported by Secret Server
        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateSet('GET', 'DELETE', 'PATCH', 'POST', 'PUT')]
        [string]
        $Method,

        # Specifies the body of the request.
        [Parameter(ValueFromPipelineByPropertyName)]
        [Object]
        $Body,

        # Specifies the file path to write the content.
        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $OutFile,

        # Specifies the content type of the web request.
        # If this parameter is omitted and the request method is POST, Invoke-RestMethod sets the content type to application/x-www-form-urlencoded. Otherwise, the content type is not specified in the call.
        [string]
        $ContentType = 'application/json',

        # Header of the web request. Enter a hash table or dictionary.
        [System.Collections.IDictionary]
        [Alias('Header')]
        $Headers,

        # Indicates using the credentials of the current user to send the web request (winauth).
        [Alias('UseDefaultCredential')]
        [switch]
        $UseDefaultCredentials,

        # Specifies that the cmdlet uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.
        [uri]
        $Proxy,

        # Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.
        # Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.
        # This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
        [PSCredential]
        [Management.Automation.CredentialAttribute()]
        $ProxyCredential,

        # Indicates that the cmdlet uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.
        # This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
        [switch]
        $ProxyUseDefaultCredentials,

        # Output a custom type name for the results.
        [Parameter(ValueFromPipelineByPropertyName)]
        [string[]]
        $PSTypeName,

        # A set of additional properties to add to an object
        [Parameter(ValueFromPipelineByPropertyName)]
        [Collections.IDictionary]
        $Property,

        # A list of property names to remove from an object
        [string[]]
        $RemoveProperty,

        # Expand a given property from an object
        [string]
        $ExpandProperty
    )

    process {
        #region Prepare Parameters
        $irmSplat = @{ } + $PSBoundParameters    # First, copy PSBoundParameters and remove the parameters that aren't Invoke-RestMethod's
        $irmSplat.Remove('PersonalAccessToken') # * -PersonalAccessToken
        $irmSplat.Remove('PSTypeName') # * -PSTypeName
        $irmSplat.Remove('Property') # *-Property
        $irmSplat.Remove('RemoveProperty') # *-RemoveProperty
        $irmSplat.Remove('ExpandProperty') # *-ExpandProperty
        if ($PersonalAccessToken) {
            # If there was a personal access token, set the authorization header
            if ($Headers) {
                # (make sure not to step on other headers).
                $irmSplat.Headers.Authorization = "Bearer $PersonalAccessToken"
            } else {
                $irmSplat.Headers = @{
                    Authorization = "Bearer $PersonalAccessToken"
                }
            }
        } else {
        }
        if ($Body -and $Body -isnot [string]) {
            # If a body was passed, and it wasn't a string
            # $irmSplat.Body = $Body | ConvertTo-Json -Depth 100 # make it JSON.
        }
        if (-not $irmSplat.ContentType) {
            # If no content type was passed
            $irmSplat.ContentType = $ContentType # set it to the default.
        }
        #endregion Prepare Parameters

        #region Call Invoke-RestMethod

        # We call Invoke-RestMethod with the parameters we've passed in.
        # It will take care of converting the results from JSON.
        Invoke-RestMethod @irmSplat |
            & { process {
                    $in = $_
                    # What it will not do is "unroll" them.
                    if ($in -eq 'null') {
                        return
                    }
                    if ($ExpandProperty) {
                        if ($in.$ExpandProperty) {
                            $in.$ExpandProperty
                        }
                    } elseif ($in.code -like '*API_*') {
                        $PSCmdlet.WriteError(
                            [Management.Automation.ErrorRecord]::new(
                                [Exception]::new("$($in.message)"), "$($in.code)", 'InvalidOperation', $in))
                        $PSCmdlet.WriteVerbose("$in")
                        return
                    } elseif ($in -notlike '*<html*') {
                        # Otherwise, As long as the value doesn't look like HTML,
                        $_ # pass it down the pipe.
                    } else {
                        # If it happened to look like HTML, write an error
                        $PSCmdlet.WriteError(
                            [Management.Automation.ErrorRecord]::new(
                                [Exception]::new('Response was HTML, Request Failed.'),
                                'ResultWasHTML', 'NotSpecified', $in))
                        $PSCmdlet.WriteVerbose("$in") # and write the full content to verbose.
                        return
                    }
                    # Redirect standard error (2) to same place as standard output (1)
                } } 2>&1 |
            & { process {
                    # One more step of the pipeline will unroll each of the values.
                    if ($_ -is [string]) { return $_ }
                    if ($null -ne $_.Count -and $_.Count -eq 0) { return }
                    if ($PSTypeName -and # If we have a PSTypeName (to apply formatting)
                        $_ -isnot [Management.Automation.ErrorRecord] # and it is not an error (which we do not want to format)
                    ) {
                        $_.PSTypeNames.Clear() # then clear the existing typenames and decorate the object.
                        foreach ($t in $PSTypeName) {
                            $_.PSTypeNames.add($T)
                        }
                    }

                    if ($Property) {
                        foreach ($propKeyValue in $Property.GetEnumerator()) {
                            if ($_.PSObject.Properties[$propKeyValue.Key]) {
                                $_.PSObject.Properties.Remove($propKeyValue.Key)
                            }
                            $_.PSObject.Properties.Add($(
                                    if ($propKeyValue.Value -as [ScriptBlock[]]) {
                                        [PSScriptProperty]::new.Invoke(@($propKeyValue.Key) + $propKeyValue.Value)
                                    } else {
                                        [PSNoteProperty]::new($propKeyValue.Key, $propKeyValue.Value)
                                    }))
                        }
                    }
                    if ($RemoveProperty) {
                        foreach ($propToRemove in $RemoveProperty) {
                            $_.PSObject.Properties.Remove($propToRemove)
                        }
                    }
                    return $_ # output the object and we're done.
                } }
        #endregion Call Invoke-RestMethod
    }
}