HowToGraphQL.com Notes

09 Aug 2020 🔖 graphql web development
💬 EN

I stumbled into the Party Corgi Discord, a community of front-end web developers who produce a lot of written, audio, and video content teaching and learning the tech they use.

I happened to be online when the opportunity arose to study HowToGraphQL.com as a group, which is great because at work my team just got access to a new product that uses GraphQL (an HTTP-based communications specification), and I had no idea in the slightest how to use it until I started playing with Gatsby a month ago. I thought it’d be fun to follow others’ lead and take notes in public.

It’s all about the joins

Using REST-based API endpoints with interconnected data can often feel like the exercise in the for-loop-based “manual joining” my Big Data professor taught us on a whiteboard when we were all mystified how to leave the world of SQL behind.

GraphQL was, among other concerns, developed to make writing HTTP requests for data a little more like writing SQL or Salesforce’s “SOQL.” All a coder worries about, even when wanting to “join” data, is writing a declarative query.

Delegating overhead to frameworks

Apparently a lot of coders writing GraphQL don’t bother to write the HTTP requests over which GraphQL-syntax code is sent, any more than SQL programmers bother to hand-write ODBC connection details into their codebases.

Such concerns are usually delegated to frameworks within the language in which software using a GraphQL-based API is being written.

These frameworks also often help with caching data in ways that avoid extra HTTP requests later on.

In contrast, it’s apparently much more common for coders to hand-write their HTTP request details when making calls to REST-based APIs.

Comparisons to other query languages

At first I wondered if I could make a post like “Every SQL Join You’ll Ever Need” about GraphQL, but upon realizing how much it depends upon “joins” predefined “on the backend,” I realized that a more appropriate inspiration would be the classic Salesforce article “SOQL – How I Query With Thee, Let Me Count the Ways”.

It makes some sense – the “O” in “SOQL” does stand for “object.”

Like SOQL, it appears you can’t just arbitrarily cross-join “relations” to your heart’s desire the way you can in SQL. Instead, foreign-key / primary-key (parent-child) relationships are pre-defined as part of the “allowed queries.”

I doodled the following notes on paper:

SOQL

SELECT Id, Name, (SELECT Id, Name, LastModifiedDate FROM Children__r)
FROM ParentObject__c

GraphQL

{
  allParentObjects {
	Id
	Name
	Children {
	  Id
	  Name
	  LastModifiedDate
	}
  }
}

But then I realized … maybe not so much.

allParentObjects is supposed to correspond to FROM ParentObject__c but has its own dedicated name made up on the fly by this particular GraphQL API’s authors (despite having a data type of “list of ParentObject-s” or [ParentObject]! in this API’s schema – which, by the way, is written in “SDL”).

On the other hand, when you do a Salesforce subquery, the FROM inside the parentheses gets a special name (in the case of custom objects, defined by you – e.g. Children__r for the Child__c object) that’s different than the “table” name, so … having “different names for different parts of a query” isn’t completely foreign to SOQL-type concepts.

That said, it’s different enough that I think I need to abandon all hope of making comparisons between GraphQL and other declarative query / data-modification languages.

Okay – one more “comparison.” Unlike SOQL/Apex and more like SQL/DML, GraphQL has a “data modification” syntax that looks a lot like its “query” syntax.

(GraphQL also has a similar-looking syntax for “subscriptions,” which looks interesting to learn more about.)

Other corgis’ notes

(Coming soon)

Credits

Thank you, corgi Chris Biscardi, for the upgraded post header image!

Posts in this series