
Tutorial: Designing a GraphQL API - mengledowl
https://gist.github.com/swalkinshaw/3a33e2d292b60e68fcebe12b62bbb3e2
======
chao-
Solid writeup. Happy to see I am not crazy in the conclusions I had drawn in
my first GraphQL project. Or if I am crazy, at least I am not alone.

However, on the topics of pagination and authorization, it took many hours of
comparing differing viewpoints across guides, blogs, videos and so forth to
puzzle out where the lines were between GraphQL itself, and the way it is
often "experienced" by developers (i.e. filtered through the lens of Relay or
Apollo). So when this tutorial says:

 _> For situations like this, GraphQL provides for list pagination... the
necessary architecture around [connection types] are well-specified and will
be taken care of at implementation time._

I have to push back.

GraphQL does not "provide for" pagination out of the box any moreso than the
abstract concepts in REST "provide for pagination" out of the box. Or RPC. Or
what-have-you. The GraphQL website _suggests_ an implementation for pagination
that seems to translate to "Relay is opinionated and does it this way", only
without calling Relay by name [0]. It then leaves a bunch of questions open
with the whole "connection" metaphor, as it relates to types. That was both
confusing and a shame, because the rest of the explanations involving types in
the GraphQL guide are solid. Trying to uncover why Relay does this, I sought
to compare it to Apollo, and their answer for pagination seemed to be _"
Whateva' ya want, kid! Go nuts!"_, so at least they are honest about it being
a question open to many answers [1].

Similarly for authorization, GraphQL suggests things by saying "Well... that's
not a GraphQL problem", which is true! Mostly! In my case the story was
happier than with pagination. For our particular domain, where stock libraries
providing "roles" don't cut it, GraphQL forced me to rethink our authorization
more systematically than our existing REST interface did.

It finally "clicked" for me on both topics while reading a really minor sub-
point in the GraphQL pagination article that reminded me that, in the
mathematical notion of a graph, an edge can have properties just as a node
can. Maybe no one besides me had this problem, but after a decade steeped in
the entity-centric lens common to REST API implementations, it was something I
had become unintentionally blind to.

[0]
[https://graphql.org/learn/pagination/](https://graphql.org/learn/pagination/)

[1]
[https://www.apollographql.com/docs/react/features/pagination...](https://www.apollographql.com/docs/react/features/pagination.html)

\--

Edit/Afterthought: I realize that this is an internal doc from Shopify, so if
their statement "will be taken care of at implementation time" was meant to
just hand-wave for an audience of front-end engineers, that is a reasonable
thing to say. I don't mean to be too critical without having the context, I
just needed to vent about my first encounters with GraphQL.

~~~
k__
Isn't the Relay way the de facto standard?

~~~
andrewingram
The Relay patterns are are decent starting point, but even if using Relay
they're more-or-less optional

Relay connections (cursor-based pagination) are decent for many reasonable use
cases, but if you absolutely do need random access (let's say you have a
virtualized list where a user can scroll quickly to a specific point and load
only the data local to it), you'll have to bring your own pagination solution.

------
goddtriffin
Great document. Very useful for maturing a GraphQL API past that of a cloned
tutorial.

