Update Invoke-GHRestMethodMultipleResult to take a body

[HowardWolosky]

Feature Idea Summary

When writing up the workaround for #289, I realized that there are GET API's which may have multiple pages of results where we need to send a body. Therefore, Invoke-GHRestMethodMultipleResult needs to be updated to take in a body, just like Invoke-GHRestMethod.

Feature Idea Additional Details

An alternate approach to this would be to make Invoke-GHRestMethod the common entry-point for both single and multi-page results, and have its internal implementation simply call out to two different internal-only helper methods. Get methods could always call into the "multi-result" internal helper, because that would work fine even for a result with a single-page.

Requested Assignment

I'm leaving this open for someone else to tackle. If no-one expresses interest in the next week or so, I'll take it on myself.

Operating System

OsName               : Microsoft Windows 10 Pro
OsOperatingSystemSKU : 48
OsArchitecture       : 64-bit
WindowsVersion       : 2004
WindowsBuildLabEx    : 19041.1.amd64fre.vb_release.191206-1406
OsLanguage           : en-US
OsMuiLanguages       : {en-US}

PowerShell Version

Name                           Value
----                           -----
PSVersion                      5.1.19041.1
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.19041.1
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Module Version

Running: 0.15.1
Installed:

[divya661]

Hello, sir Howard Wolosky (@HowardWolosky)
I would like to work on this issue. I'm new to this repository so might need your guidance. Is there any other medium too for asking related queries to connect with you.

[HowardWolosky]

DIVYA CHAUHAN (@divya661) - Welcome to the project! You're welcome to try out this change yourself.

This is the best method of reaching out for questions, that way other people will have the opportunity to also help you if they know the answer, or learn if they have the same question.

[divya661]

Hi Jack Samuel S (@jaxxstar) Are you also working on this part too, as you have shown interest in working on issue #289 ?

[divya661]

Howard Wolosky (@HowardWolosky) Sry for the late response. I want to confirm, as you said "internal implementation simply call out to two different internal-only helper methods", the two internal helpers you are discussing is one for single-page result and other for multiple page result or could you explain a bit more about it, if I haven't got your point correctly? I have to make changes in such a way, that the API should allow for pagination? I've explored the code of these functions by now.

[HowardWolosky]

I was imagining something like this:

1. What is currently known as Invoke-GHRestMethod should be renamed to an internal helper method...possibly Invoke-GHRestMethodInternal

2. What is currently known as Invoke-GHRestMethodMultipleResult should be renamed to Invoke-GHRestMethod and given an alias back to Invoke-GHRestMethodMultipleResult.

3. The new Invoke-GHRestMethod should be updated to have all of the same parameters as Invoke-GHRestMethodInternal.

4. Invoke-GHRestMethod should get the following new parameters as well:

   • MaxResultPages - [int] - The maximum number of pages of results to follow if this is a multi-page response. If not defined (or < 1), will return all pages
   • ``SinglePage- [switch] - (well, it already had this one before, but should still have it). The equivalent of settingMaxResultPages` to `1`. Should fail if the caller specifies both `MaxResultPages` and `SinglePage`.

• (optional -- could be added in a future PR as this isn't required right now): StartAt - [int] - Indicate what page to start at in a request that has multiple pages of results. The API docs talk about pagination and how to form that request.

5. Update the logic in Invoke-GHRestMethod to pass in all of the relevant parameters to Invoke-GHRestMethodInternal, and to appropriately limit the looping based on MaxResultPages, which means you'd set $MaxResultPages to an appropriate value at the top of the loop, and then loop until iterations match $MaxResultPages or there's no further next link. You'll also need to update the status display logic to take into account $MaxResultPages relative to $result.numPages and $multiRequestProgressThreshold (you need to make sure that you're using $MaxResultPages instead of $result.numPages if $MaxResultPages is smaller).

With all of those changes, it should then be possible to consistently call Invoke-GHRestMethod regardless of the API having a single or multi-page response, and callers can still control how many pages of results that they get back (so they can still get a single-page result experience if they wanted to).

Does that all make sense?

[divya661]

Yeah, got it