Improve paging of Invoke-WikiMethod

[lipkau]

Description

The current implementation of Invoke-WikiMethod's paging does not support the pipeline correctly.

Demonstration

$result = Get-WikiPage -Space Foo -PageSize 100
$result.Count # = 1000

This code will have invoked Invoke-WikiMethod 10 time where each invocation returned a result set of 100 entries. Resulting in a collection of 1000 in total.

$result = Get-WikiPage -Space Foo -PageSize 100 | Select-Object -First 50
$result.Count # = 1000

This code will have done the same as the first, but will later select the first 50 entries of the result set and return them - where only 1 invocation of Invoke-WikiMethod would have been enough.

Fix

Invoke-WikiMethod must be updated so that it will no longer append to arrays, but return to StdOut at once:

# None paginated results / first page of pagination
if (($result) -and ($result | Get-Member -Name results)) {
    $result = $result.results
}
if($OutputType) { 
    $result | & $converter
} else {
    $result
}

if ($result._links.next) {
   Write-Verbose "[Invoke-WikiMethod] Invoking pagination"

   # Self-Invoke function for recursion
   $parameters = @{
       URi = "{0}{1}" -f $result._links.base, $result._links.next
       Method = $Method
   }
   if ($Body) {$parameters["Body"] = $Body}
   if ($Headers) {$parameters["Headers"] = $Headers}
   if ($GetParameters) {$parameters["Get$GetParameters"] = $GetParameters}

   Write-Output Invoke-WikiMethod @parameters
}

Additionally

[CmdletBinding(SupportsPaging = $true)] enables a function to support paging on itself.
This exposes parameters such as -Skip, -IncludeTotalCount and -First.
this could be implemented in the likes of:

$PSBoundParameters["Skip"] = $PSCmdlet.PagingParameters.Skip + $result.Count
$PSBoundParameters["First"] = $PSCmdlet.PagingParameters.First - $result.Count
Invoke-WikiMethod @PSBoundParameters

[lipkau]

Other good sample:
https://github.com/PowerShell/PowerShell/blob/master/demos/rest/rest.ps1

[JohnLBevan]

Relating to SupportsPaging, I knocked up some PoC code to ensure I've understood how that should be implemented... https://codereview.stackexchange.com/questions/164252/powershell-supports-paging

We may also be able to make use of some of the logic from the Invoke-DummyRestMethod when writing related tests/mocks.

[JohnLBevan]

If the function's called without making use of the paging parameters; or if the page size is greater than the web service's supported page size, is there any preference on behaviour?

i.e. With SupportsPaging, the calling code needs to be aware of the page size, and to implement logic to loop through page by page if you want all results. If we want all results returned by a single call to the method, we want the function's internal code to loop through those pages. Would we still want to specify a page size for the function (i.e. which gets passed to the web service's limit parameter), or where we want all results would we not make use of the function's SupportsPaging, even though behind the scenes we are making paged calls to the web service?

[lipkau]

If no stepsize is provided, use the systems default or leave the limit out.
If no paging parameter is provided, SupportPaging will still be active but not used.

[lipkau]

• We will return everything unless the SupportPaging parameters restrict it.
• The StepSize will only influence the amount of results per call. Which is useful for slow connection and for | Select -First 10.
• In order for the pipe to be able to terminate the calls, we are not allowed to collect the results in an array before writing to output.

[lipkau]

my first attempt:
lipkau@157832d
brianbunke/ConfluencePS@develop...lipkau:feature/CmdLetPaging