Tutorial: Designing a GraphQL API
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.<p>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:<p><i>> 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><p>I have to push back.<p>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 <i>suggests</i> 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 <i>"Whateva' ya want, kid! Go nuts!"</i>, so at least they are honest about it being a question open to many answers [1].<p>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.<p>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.<p>[0] <a href="https://graphql.org/learn/pagination/" rel="nofollow">https://graphql.org/learn/pagination/</a><p>[1] <a href="https://www.apollographql.com/docs/react/features/pagination.html" rel="nofollow">https://www.apollographql.com/docs/react/features/pagination...</a><p>--<p>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.