Improve API pagination support

[JGAntunes]

Currently pagination is dictated via the open-api spec support and, for the list endpoints that support it, users will need to rely on the per_page and page params to iteratively fetch new data. The fact that we're not exposing the response headers also means users will have no way to know when further data is available or not.

We should figure a user friendly API mechanism to deal with this - e.g. #39 (comment) 👍

[IanVS]

I think it could also be valuable to mention pagination in the README. I had to dig a little to determine how to use page and per_page.

[erezrokah]

Linking https://github.com/netlify/cli/blob/0eea04d7d0cb65f4ca1c90dbc95ccc7116cee159/src/lib/api.js#L87 as an example also in case someone would like to add it to the README as a contribution.

[GonzaloHirschToptal]

Bumping this because we need to retrieve paginated results and we are missing pagination information the API returns.

[mfanuzzi]

Just updating this for anyone else who might come across it. A further complication is that the maximum per_page is 100.

https://answers.netlify.com/t/upper-limit-on-per-page-within-api-calls/53859/2