Tutorial: Designing a GraphQL API | Hacker News Reader

Tutorial: Designing a GraphQL API

gist.github.com

180 pointsmengledowl12 comments

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/

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

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.

It really is a shame, that the GraphQL specs don't have pagination and auth. ( https://github.com/facebook/graphql/issues/4 ) It would have finally ended the bickering about how to design "RESTful APIs", there's the specs, that's it. (Sure, there are a dozen REST-ish API descriptors and schema thingies, but they got nowhere, as far as I know.)

What do you need for auth other than some mechanism of providing an auth token with each query (usually via an HTTP header)?

Authorization != Authentication.

Pas, who you are responding to, used the more ambiguous abbreviation of "auth", but I was specifically referring to authorization, not authentication. So once you are authenticated, i.e. once I know who you are, what are you allowed to do? This is a deeper, domain-specific question, and the GraphQL guide rightly points out that this doesn't belong in whatever glue layer exists between your domain logic and the schema you expose.

My question was essentially for both expansions of auth. Because as far as I'm concerned, as long as your API layer provides some means of determining user identity, everything else related to auth should be the responsibility of lower layers. It was largely a rhetorical question, because people have been asking for GraphQL to solve non-GraphQL problems since 2015.

Do you mean HTTP as the lower layer? I can see authentication (or better said session persistence) handled by a HTTP header, but I don't really see how HTTP by default provides options for what mutations and queries the client should be able to issue. There's no ACL descriptor for GraphQL.

And even the choice of HTTP header for Authentication is debated enough, that I think it should have been bolted down in the GQL specs.

Isn't the Relay way the de facto standard?

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.

The Relay way is one common style, but I wouldn't call anything a standard at this point. It feels to me like it's OK if this area needs some time to settle, as there are a few styles that work well for different use-cases, and people are still figuring out if there are better ways out there.

The apollo docs lightly touch on a few styles https://www.apollographql.com/docs/react/features/pagination...

I'm the person who created that Gist for sharing it publicly and I do agree that GraphQL makes pagination confusing. Just yesterday I was searching for a link to share with someone and came across that official page which uses Relay-style connections without naming OR even linking to it which I found very weird.

> 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.

Thank you for pointing this out. I did edit the document to remove Shopify specific mentions and sentences like this, but this one is subtle. I'll likely edit it to be a little clearer and even link to the Relay spec.

edit: I've updated that section. Hopefully it's clearer now :)

Looks good. I think it will be of great help to anyone reading it to have those two links for a little framing.

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

Reply on news.ycombinator.com