api: output a single JSON array in REST pagination mode

[mislav]

When fetching N pages, avoid printing N separate JSON arrays to the output stream. Instead, massage the output so that the N pages of data are merged into a single JSON array. This is achieved by omitting the final ] for the first page, and omitting the initial [ for all subsequent pages.

Fixes #1268 (for REST pagination)

[heaths]

It's an elegant solution for REST, but I can't imagine how this might work for GraphQL where arrays are nested and may be numerous. Even if you kept track of scope e.g., JSON elements, where arrays are found, you still couldn't write directly to stdout.

With new APIs being added to GraphQL only (last I read), perhaps this is not an issue now if GraphQL usage is light but I imagine that will increase over time. That said, most of what users probably need to do is represented by REST anyway, and as long as those don't go away maybe this solves the 75% (or whatever) case.

Though it'd be ideal to make it just work for GraphQL, jq -s or https://github.com/heaths/gh-merge-json can work around this (and I'm sure some other ways) can work around the problem if suddenly buffering responses for GraphQL requests is a concern.

[mislav]

Thanks for reviewing! I think it might be useful to solve paginated JSON outputs separately for REST (since that's relatively trivial, as showcased here) and for GraphQL, which I'm becoming more open to do your way, i.e. using buffering.