Pagination for returning large pinsets

[lidel]

When making a call to GET /pins there can be a lot of results to return.

Should we add pagination support under something like /pins/page?limit=100&skip=2? Do nothing? Or is there a better way to tackle this (eg. GraphQL suggested in #8 provides various pagination strategies)?

Ref. https://cloud.google.com/apis/design/design_patterns#list_pagination

[obo20]

I would strongly support pagination as not only an option, but also a default for the GET /pins endpoint.

Maybe something like a default of 10 pins per page (but this can be changed by simply passing in a new limit).

Also, I would recommend having a "max" page limit of something like 1000 so people don't just put something like 238947239847 as their limit.

[lidel]

Pagination based on limit and skip is introduced in #14 with max limit of 1000.

@achingbrain @obo20 remaining pagination question: how should API indicate that there are more records?

Potential solutions:

• Do nothing. When exactly 1k of items is returned, clients send potentially redundant &skip=1000 to see if more items are present.
• Return X-Pins-Total-Count HTTP header with partial responses to indicate if more records are available
• Wrap response list in object that has total count value as a property
• Something else?

[obo20]

Our API should be able to handle counting the total number of records that match a query. This shouldn't be a huge problem for us to implement either way. Currently we return counts as part of the return object as a property, but I suppose a header would work as well.

[lidel]

@obo20 I think HTTP header is the easiest, but it makes it much harder for people to re-implement this API in non-HTTP contexts internally.

I've added PinResults object with count fields in #20, hopefully thats the least painful option.