DbWebApi-Client.psm1

<#
	.SYNOPSIS 
	Sends an HTTP or HTTPS request to a RESTful web service - simplified for DbWebApi invoking.

	.DESCRIPTION
	The Invoke-DbWebApi function wraps the Invoke-RestMethod cmdlet which sends HTTP and HTTPS requests to Representational State Transfer (REST) web services that returns richly structured data, and simplified the parameters preparation for DbWebApi invoking.

	Windows PowerShell formats the response based to the data type. For an RSS or ATOM feed, Windows PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, Windows PowerShell converts (or deserializes) the content into objects.

	The Invoke-RestMethod cmdlet was introduced in Windows PowerShell 3.0.

	.COMPONENT
	Invoke-RestMethod

	.INPUTS
	System.Object. You can pipe the body of a web request to Invoke-DbWebApi. The $Body will be passed in as-is to Invoke-RestMethod if it is a string, otherwise it will be treated as a object and converted to JSON string before passing to Invoke-RestMethod if ContentType is "application/json".

	.PARAMETER Uri
	Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is sent. This parameter supports HTTP, HTTPS, FTP, and FILE values.

	(Inherited from Invoke-RestMethod)

	.PARAMETER Method
	Specifies the method used for the web api request. Defaults to Post.

	(Inherited from Invoke-RestMethod)

	.PARAMETER Body
	Enhanced: The Body value will be passed in as-is to Invoke-RestMethod if it is a string, otherwise it will be treated as a object and converted to JSON string before passing to Invoke-RestMethod if ContentType is "application/json".

	(Inherited from Invoke-RestMethod)

	.PARAMETER ContentType
	Specifies the content type of the web request. If this parameter is omitted, Invoke-DbWebApi sets the content type to "application/json".

	(Inherited from Invoke-RestMethod)

	.PARAMETER InFile
	Gets the content of the web request from a file.

	Enter a path and file name. If you omit the path, the default is the current location.

	(Inherited from Invoke-RestMethod)

	.PARAMETER OutFile
	Saves the response body in the specified output file. Enter a path and file name. If you omit the path, the default is the current location.

	By default, Invoke-DbWebApi returns the results to the pipeline. To send the results to a file and to the pipeline, use the Passthru parameter.

	(Inherited from Invoke-RestMethod)

	.PARAMETER PassThru
	Returns the results, in addition to writing them to a file. This parameter is valid only when the OutFile parameter is also used in the command.

	(Inherited from Invoke-RestMethod)

	.PARAMETER Credential
	Specifies a user account that has permission to send the request.

	(Inherited from Invoke-RestMethod)

	.PARAMETER BasicAuth
	Force to send the Basic Authorization header on the initial request if the Credential is presented. The plaintext username and password will be extracted from Credential parameter (PSCredential class).

	By default, Invoke-RestMethod will not send the Authorization header on the initial request. It waits for a challenge response then re-sends the request with the Authorization header.

	.PARAMETER Headers
	Specifies the headers of the web request. Enter a hash table or dictionary.

	(Inherited from Invoke-RestMethod)

	.PARAMETER Certificate
	Specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate.

	(Inherited from Invoke-RestMethod)

	.PARAMETER CertificateThumbprint
	Specifies the digital public key certificate (X509) of a user account that has permission to send the request. Enter the certificate thumbprint of the certificate.

	Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.

	(Inherited from Invoke-RestMethod)

	.PARAMETER DisableKeepAlive
	Sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.

	(Inherited from Invoke-RestMethod)

	.PARAMETER TimeoutSec
	Specifies how long the request can be pending before it times out. Enter a value in seconds. The default value, 0, specifies an indefinite time-out.

	(Inherited from Invoke-RestMethod)

	.PARAMETER MaximumRedirection
	Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.

	(Inherited from Invoke-RestMethod)

	.PARAMETER SessionVariable
	Creates a web request session and saves it in the value of the specified variable. Enter a variable name without the dollar sign ($) symbol. You cannot use the SessionVariable and WebSession parameters in the same command.

	(Inherited from Invoke-RestMethod)

	.PARAMETER TransferEncoding
	Specifies a value for the transfer-encoding HTTP response header. Valid values are Chunked, Compress, Deflate, GZip and Identity.

	(Inherited from Invoke-RestMethod)

	.PARAMETER UserAgent
	Specifies a user agent string for the web request.

	(Inherited from Invoke-RestMethod)

	.PARAMETER WebSession
	Specifies a web request session. Enter the variable name, including the dollar sign ($). You cannot use the SessionVariable and WebSession parameters in the same command.

	(Inherited from Invoke-RestMethod)

	.NOTES
	Since the Invoke-DbWebApi is just a simple wrap of the build-in Invoke-RestMethod cmdlet.
	Please see https://technet.microsoft.com/en-us/library/hh849971.aspx for more detail.

	.EXAMPLE
	$Response = Invoke-DbWebApi -Uri https://test-server:8089/something -Body @{inParamA = [DateTime]"2015-03-16"; inParamB = 108; inParamC = "Hello"}

	.LINK
	https://github.com/DataBooster/DbWebApi

	.LINK
	https://technet.microsoft.com/en-us/library/hh849971.aspx
#>

Function Invoke-DbWebApi {
	[CmdletBinding(SupportsShouldProcess)]
	Param (
		[Parameter(Mandatory)]
		[Uri]$Uri,
		[Parameter()]
		[Microsoft.PowerShell.Commands.WebRequestMethod]$Method = [Microsoft.PowerShell.Commands.WebRequestMethod]::Post,
		[Parameter(ValueFromPipeline)]
		$Body,
		[Parameter()]
		[string]$ContentType = "application/json",
		[Parameter()]
		[string]$InFile,
		[Parameter()]
		[string]$OutFile,
		[Parameter()]
		[switch]$PassThru,

		[Parameter()]
		[PSCredential]$Credential,
		[Parameter()]
		[switch]$BasicAuth,

		[Parameter()]
		[System.Collections.IDictionary]$Headers,
		[Parameter()]
		[System.Security.Cryptography.X509Certificates.X509Certificate]$Certificate,
		[Parameter()]
		[string]$CertificateThumbprint,
		[Parameter()]
		[switch]$DisableKeepAlive,
		[Parameter()]
		[int]$TimeoutSec,
		[Parameter()]
		[int]$MaximumRedirection,
		[Parameter()]
		[string]$SessionVariable,
		[Parameter()]
		[string]$TransferEncoding,
		[Parameter()]
		[string]$UserAgent,
		[Parameter()]
		[Microsoft.PowerShell.Commands.WebRequestSession]$WebSession
	)

	Begin
	{
		if ($Credential) {
			if ($BasicAuth) {
				$basicAuthHeader = "Basic " + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($($Credential.UserName) + ":" + $($Credential.GetNetworkCredential().Password)));
				if ($Headers) {
					$psBoundParameters.Headers["Authorization"] = $basicAuthHeader;
				}
				else {
					$psBoundParameters.Headers = @{ Authorization = $basicAuthHeader };
				}
				$psBoundParameters.Remove("BasicAuth") | Out-Null;
				$psBoundParameters.Remove("Credential") | Out-Null;
			}
		}
		else {
			$psBoundParameters.UseDefaultCredentials = $true;
		}

		if (!$psBoundParameters.ContainsKey("Method")) {
			$psBoundParameters.Method = $Method;
		}

		if (!$psBoundParameters.ContainsKey("ContentType")) {
			$psBoundParameters.ContentType = $ContentType;
		}
	}

	Process
	{
		if ($Body -and $ContentType -eq "application/json" -and $Body -isnot [string]) {
			$psBoundParameters.Body = ConvertTo-Json $Body;
		}

		if ($PSCmdlet.ShouldProcess("Invoke-RestMethod -Uri '$Uri' ...")) {
			Invoke-RestMethod @psBoundParameters;
		}
		else {
			Write-Verbose (ConvertTo-Json $psBoundParameters);
		}
	}
}