by Antwan Wimberly
18 June, 2019
When you Should use GraphQL
The biggest issue I foresee with using GraphQL is that it actually has implications at the API level:
https://graphql.org/learn/thinking-in-graphs/#business-logic-layer https://graphql.org/learn/serving-over-http/ https://github.com/graphql/express-graphql https://github.com/apollographql/apollo-server
I believe a common misconception is that we can simply point our client at existing web APIs and it’ll seamlessly work. On the contrary, someone actually has to be on the hook for building the API server that interprets the semantics of each mutation (mutations and queries are separate concepts similar to command and queries within CQRS) and query:
You also need to spec out the schemas for each “resource” (I’m probably using the wrong vernacular but you get me).
Authentication and authorization are also separate concerns:
Lastly, you’d have to adapt each command/query to the underlying data store that houses the data you’re targeting (it works very nicely with mongodb since the operators/semantics of graphql map nicely to the mongodb API e.g. filter, projections/select clauses, etc.). A fair amount of skill is also required (an understanding of resolvers) if you want to avoid N + 1s as well (this is typically experienced with ORMs like NHibernate and Entity Framework. I’ve had to use NHibernate profiler in the past to circumvent these issues due to lazy loading/proxied collections that perform joins on the fly).
As you can probably see, things can get complicated in a hurry. A good friend of mine discussed his experience with GraphQL in the past so I’ve tried to learn from this. I think there are valid use cases for when it should be used (e.g. dynamic search/reporting where a client provides a user generated query that will always vary in nature, clients that need to load different data based on device type, or a demand for rich querying capabilities that make the nested querying capabilities of graphql shine), but we should let these clients, use cases, more granular data models/domains (e.g. github.com - they’ve becomes huge graphql advocates over the years and have even attempted to contribute to the spec) identify themselves and stick to YAGNI and KISS in the meantime (not all developers agree with these principles - I used to be one of them - but as time has progressed they’ve both helped me tremendously). In any case we should aim to avoid over-engineering at all costs.
The Jira rest API also makes sense to expose over GraphQL as they have a fair amount of hierarchical data with nesting and also need to expose a rich querying model over HTTP. I have worked with their API in addition to github and they thing they both have in common is that they’re centered around content. The ability to get content in and out is crucial for both companies. A lot of the Jira resources exposed over HTTP have support for projection (specifying a whitelist for fields because fetching the entire resource can be expensive at times). I don’t think our problem domain in the automotive industry is hardly comparable to either. You can find the Jira server plugin I maintained for QASymphony at:
I was unable to open source our cloud plugin but I built that using ace editor, mongodb, node.js, and atlassian-connect-express:
Social platforms in general seem to be really good candidates for using GraphQL (especially when the number of fields and the length of assets or content is arbitrary as opposed to fixed length/more predictable). In GitHub, files can be really small or really large. In Jira, an issue type can have an arbitrary number of fields of different type (image, video, text, document, etc.), size, and length. Even the layout of a given issue type can be dynamic and specified at the plugin level (e.g. atlassian-connect-express allows a plugin to specify its weight which determines how far from the top the plugin is rendered relative to others on the page). Jira plugins can even specify what section of the Jira website they're located in (header, sidepanel, etc.). The larger more enterprise based domains that have a fair amount of variance within their APIs can get a much higher yield from GraphQL (I think Slack is also a domain of this nature with it being a social platform and exposing a plugin model in addition to a public facing API). For smaller apps and more controlled domains (e.g. the number of fields is fixed and most all fields have a predictable content type, upper-bound/max length, etc.) I feel traditional web APIs make a ton more sense.
Newer tech is considered cool, contemporary, will make some folks more marketable, is considered more elegant, allows developers to focus more on the what as opposed to the how (I’m absolutely familiar with and an advocate for declarative/meta-programming and have been since my Washington, D.C. days), but there is a time a place for all the things in my experience and there’s no such thing as free lunch (every choice we make has an associated cost).