Add support for auto-pagination

[ob-stripe]

r? @remi-stripe
cc @stripe/api-libraries

Adds support for auto-pagination.

Example usages:

var service = new BalanceTransactionService();
var listOptions = new BalanceTransactionListOptions
{
  Created = new DateRangeOptions
  {
    GreatherThanOrEqual = DateTime.Parse("2018-11-01T00:00:00Z"),
    LessThan = DateTime.Parse("2018-12-01T00:00:00Z"),
  },
  Limit = 100,
};

foreach (var balanceTransaction in service.ListAutoPaging(listOptions))
{
  // Do something with balanceTransaction
}

var service = new InvoiceService();
var lineItems = service.ListLineItemsAutoPaging("in_123").ToList();

The second example uses the LINQ method ToList() to directly convert the IEnumerable<LineItem> returned by InvoiceService.ListLineItemsAutoPaging() into a List<LineItem>.

Fixes #1038.

[ob-stripe]

I couldn't find a way to mock response headers, so I made the Date header optional. I think that's better anyway.

[ob-stripe]

We need the resource to have an ID in order to be able to paginate. I also added IHasId as a constraint on other interfaces where it makes sense to do so (i.e. everything except create).

[ob-stripe]

This test seems pretty complex, but it's actually pretty straightforward:

1. set up 3 stubbed requests with file fixtures
2. call ListAutoPaging
3. check invocations to make sure the correct parameters were sent

[remi-stripe]

Left some high level feedback. This looks mostly okay to me though it's still beyond what I'm comfortable actively reviewing so also cc-in @anelder-stripe

Is there a way we don't have to add new prototypes for this? I assume not but was hoping you could do an autoPaginate = true that defaults to false?

[remi-stripe]

OOC aren't we supposed to have ?starting_after=pm_124 in this URL?

[ob-stripe]

No, the API doesn't include starting_after parameters in url attributes.

[remi-stripe]

So auto-paging basically builds the entire list in ram no matter what? You can't auto page while also getting items one by one and not filling your RAM with all your BTs history?

[ob-stripe]

You can. In these examples, I used ToList() to directly convert the iterator into a list, but you can also iterate over the objects one by one:

foreach (var balanceTransaction in balanceTransactionService.ListAutoPaging(listOptions))
{
  // Do something with balanceTransaction
}

[remi-stripe]

ah neat! Can you put a test for this in our test suite? I know people refer to the test suite a lot to find example. I guess this is where your yield applies. Fun how similar it is in each language you've shown me this approach!

[ob-stripe]

Is there a way we don't have to add new prototypes for this? I assume not but was hoping you could do an autoPaginate = true that defaults to false?

No, because the types that are returned are different. When you use the existing List method, you get a StripeList<Resource> object. Auto-pagination lets you iterate directly over the Resource objects, bypassing the StripeList wrapper.

[ob-stripe]

Okay, I think this is ready to be merged. ptal @remi-stripe @anelder-stripe

[ob-stripe]

Timing out and self-approving this one :)