[bestpractices] Add connections best practice article

[dschafer]

This adds a best practices article on connections, describing how we arrived at our connections model.

[stubailo]

I'm a bit concerned about declaring connections as a general best practice for GraphQL - I find it makes APIs much more difficult to explain and implement, and it would be a detriment to GraphQL newcomers if all paginated lists were presented in this format. Does anyone else feel the same way?

[dschafer]

Yeah, it's a tricky balance to walk. Connections add a bunch of up-front complexity; you want to fetch a user and his friends, and now you're walking through nodes and edges and you're completely lost. At the same time, if you don't have cursor-based pagination, edge fields, and connection fields, you'll eventually run into the reasons why those are desirable, and adding them is a breaking change.

So my hope with this article was to walk through how we arrived at the general pagination model; ideally, by the time you get to this part of the site, you're already sold on GraphQL (so the edges/nodes don't scare you off, and you don't see them until you've ideally been convinced that they are needed), and this is describing the complexities of connections and how they can be resolved.

I tried to walk that line with the intro line and the summary at the end (which was designed to read, effectively, "this model is more complex, but more powerful"), but definitely open to edits / rewrites that help clarify things!

[stubailo]

Yeah I agree cursors are a good idea, I'm just not sold on the hop to having a cursor on every object. Usually it seems in REST people return some kind of "page" object, which has a "next page" cursor.

[dschafer]

Oh, ha, that's exactly what we do internally as well! pageInfo{endCursor, startCursor}. I'll put up a PR to mention that in the post.

[stubailo]

Yeah that would be great!

[dschafer]

Just put up #74; that adds cursors to the page info object, and notes that if the only reason you were querying for edges was to get cursors, having them on page info means having a convenience field to just get the nodes makes a lot of sense.