PSRyver

0.0.4

Public/Test-RyverApi.ps1

function Test-RyverApi {
    <#
    .SYNOPSIS
        Tests connectivity to the Ryver API.
 
    .DESCRIPTION
        This cmdlet calls the Ryver API.test method to ensure PSRyver is able to connect to
        (and invoke) API methods.
 
    .INPUTS
        A Ryver API token to use, if desired.
 
    .NOTES
        - Troy Lindsay
        - Twitter: @troylindsay42
        - GitHub: tlindsay42
 
    .NOTES
        Test-RyverApi will not, by default, use the preconfigured Ryver API token (as the
        api.test method does not require authorization).
 
    .EXAMPLE
        Test-RyverApi
        Test connectivity without authorization
 
    .EXAMPLE
        Test-RyverApi -Credential ( Get-Credential )
        Test connectivity using the specified credentials
 
    .LINK
        https://tlindsay42.github.io/PSRyver/Public/Test-RyverApi/
 
    .LINK
        https://github.com/tlindsay42/PSRyver/blob/master/PSRyver/Public/Test-RyverApi.ps1
 
    .LINK
        Invoke-RyverRestMethod
 
    .FUNCTIONALITY
        Ryver
    #>
    [CmdletBinding()]
    [OutputType( [Boolean] )]
    [OutputType( [PSCustomObject] )]
    param (
        <#
        Return the raw response object from the Ryver API, versus parsing it and
        returning a boolean.
        #>
        [Parameter( Position = 0 )]
        [Switch]
        $Raw = $false,

        <#
        Credentials to use for the Ryver API.
 
        Default value is the value set by Set-PSRyverConfig.
        #>
        [Parameter( Position = 1 )]
        [PSCredential]
        $Credential
    )

    begin {
        $function = $MyInvocation.MyCommand.Name

        Write-Verbose -Message (
            "Beginning: '${function}' with ParameterSetName '$( $PSCmdlet.ParameterSetName )' and Parameters: " +
            ( $PSBoundParameters | Remove-SensitiveData | Format-Table -AutoSize | Out-String )
        )

        if ( $PSBoundParameters.ContainsKey( 'Credential' ) ) {
            $Script:PSRyver.Authorization = ConvertTo-Authorization -Credential $Credential
            Remove-Variable -Name 'Credential'
        }
    }

    process {
        Write-Verbose -Message 'Testing Ryver API.'

        # Generate a unique value for us to use when checking requests coming back from Ryver's API
        $requestID = New-Guid
        Write-Debug -Message "Unique ID: ${requestID}"

        $params = @{
            Body        = @{
                PSRyverRequestID = $requestID
            }
            Method      = 'api.test'
            ErrorAction = 'Stop'
        }

        Write-Verbose -Message 'Calling Ryver API...'
        $response = Invoke-RyverRestMethod @params

        if ( $Raw ) {
            $response
        }
        elseif ( $response.OK ) {
            Write-Verbose -Message 'Received response from Ryver api.test call.'
            if ( $response.Args.PSRyverRequestID -eq $requestID ) {
                Write-Verbose -Message 'Unique ID matches.'
                $true
            }
            else {
                Write-Error -Message 'Ryver API call succeeded, but responded with incorrect value.'
            }
        }
        else {
            $false
        }
    }

    end {
        Write-Verbose -Message "Ending: '${function}'."
    }
}