Skip to content

[bestpractices] Add connections best practice article #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 13, 2016

Conversation

dschafer
Copy link
Contributor

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

@ghost ghost added the CLA Signed label Sep 13, 2016
@leebyron leebyron merged commit e42a3ee into new-source Sep 13, 2016
@leebyron leebyron deleted the bestpractice branch September 13, 2016 22:30
@stubailo
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

Yeah that would be great!

@dschafer
Copy link
Contributor Author

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.

jonirrings pushed a commit to jonirrings/graphql.github.io that referenced this pull request Aug 9, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants