Thoughts on GraphQL

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Well, sort of.

GraphQL isn’t really a query language. You aren’t doing basic query things like OR or, well, like LIKE, with GraphQL, at least not without a lot of hair pulling. It’s a structure language; the ‘Q’ of SQL is largely silent.

I planned on doing a big thing on GraphQL, sticking a GraphQL endpoint in DIRT while smugly wrapped in my trendiness. The more I played with it, the less appropriate it seemed.

What I walked away with was the impression that GraphQL is extremely good at a specific thing - basic CRUD operations. Which isn’t nothing. For your garden variety e-commerce apps, GraphQL is an ideal solution. If I were a betting person I’d put good money on GraphQL being built with this specific use case in mind. For the use case I made DIRT for, GraphQL hurts. A lot.

Here are my thoughts after a shallow dive into GraphQL, which was all the beer I had on hand would allow. YMMV.

GraphQL Pros

  • No over-fetching. API’s that don’t let you control the API output can give back a lot more than you need, slowing your app.
  • No under-fetching. You might need to hit several REST/HTTP API end points to get everything you need. With GraphQL you can get it all at once.
  • Go faster. If you’re a developer, you don’t have to wait around for the API folks to build what you need. If you’re an API person, rather than spending time engineering endpoints, you can say to your devs “here’s the GraphQL endpoint, fuck off”.
  • Good tooling. If you’re a “JavaScript all the things!” kind of dev, you’ll like Apollo. Most GraphQL servers also come with an interactive tool to let you test GraphQL calls.
  • CRUD all day. Basic CRUD operations are really easy with GraphQL. There are built in functions to fetch and mutate things by ID, and it understands entity relationships. You can subscribe to entities and get a push when things change.

GraphQL WTFs

  • Your devs are totally going to DDOS you, or worse. GraphQL is basically a HTTP API that takes a whole SQL statement as its argument. Clients can do quite literally anything they have permission for. Some GraphQL server libraries will let you do some oh-shit tuning, like canceling queries that run too long, but mostly it’s the wild wild west. If that doesn’t make you nervous, you are not and have never been a DBA.
  • Modeling a query with any kind of complexity in GraphQL is a pain in the ass. Queries in GraphQL are quite rigid. Good luck with that ST_DWithin() buddy. You also aren’t getting anything out of it other than a GraphQL response. If you’re trying to spit out GeoJSON or MVT, look elsewhere.
  • It’s all POST, all day. No caching for you.
  • GraphQL isn’t JSON. Stop looking like JSON. You aren’t JSON. It’s confusing.
  • allCities? WTF?! If you are using GraphQL middleware to a traditional RDBMS like Postgres, you are in for a treat. I have a table named cities. Want to query it? Ha, you get it with allCities. Yes, it takes your DB entity name and pastes a method to it. Or did you want a single city? Somebody spent a lot of time writing code to figure out cities was plural and changed it to entity/method combo City. Neat, and what the hell. There’s renaming/methodizing for all kinds of stuff, including functions. Realizing this made me go blind for 10 minutes. I get I should be thinking graphs and not schemas. But I went blind for 10 minutes.