Problem

Invoke-RestMethod is extremely useful for working with APIs that return parsable objects. My single gripe has been that it is not possible to capture the response headers. Many API's provide (sometimes critical) details via the response headers, especially rate-limiting quotas and session timeouts. In situations where information in the the response headers are required, the user must currently fall back to Invoke-WebRequest and then perform their own Content-Type detection and response-to-object conversion.

Proposal

Add a -ResponseHeadersVariable parameter to the Web Cmdlets that accepts string. this string will be used as the name of a variable in the calling scope. This variable will be set with the same contents of BasicHtmlWebResponseObject.Headers. The user can then access the variable to retrieve the headers from the previews call to Invoke-RestMethod

Example:

$GetData = Invoke-RestMethod -Uri 'http://localhost:8083/Get/' -ResponseHeadersVariable 'ResonseHeaders'
$ResponseDate = [DateTime]$ResonseHeaders.Date[0]

This example converts the Date response header to a DateTime.

The functionality would be similar to -SessionVariable. This would be available for both Web Cmdlets, though it would be redundant on Invoke-WebRequest as it would be a mirror of the returned Headers property.