Last week, the team at Notion released the beta of their new public API: https://developers.notion.com/. As a Notion user myself (but mainly as an API nerd), I took a look at what the new API looks like. Thought I’d share my findings here.

API Style

Let’s start by the API style. Some would’ve like a GraphQL API, but the team chose to go with the paved path of a JSON HTTP API. REST fans might also be bummed out, as Notion’s new API does not make use of HTTP links between resources and/or handle state. Nothing wrong with a good old HTTP…


🌱 This post is still growing and likely will change as best practices evolve 🌳

GraphQL errors are something many of us struggle with. Good practices are emerging but the community has not yet settled on a convention. I hope this guide helps demystify the many ways you can structure errors in your GraphQL servers, and the tradeoffs each of them make.

Stage 1: GraphQL Errors AKA Top-Level Errors

The GraphQL Specification describes errors quite well, so why are they even confusing in the first place?

{
"data": {
"createProduct": null
},
"errors": [
{…

GraphQL has a reputation for its N+1 problem which can often happen when implemented naively. This leads to a lot of us trying to solve the issue of data fetching with GraphQL in the most efficient way possible. Besides the popular Dataloader approach, another very common way of tackling this problem is by taking a GraphQL query, and coming up with the exact SQL needed to resolve it:

// example from Join Monster
{ SELECT
user(id: 1) { "user"."id",
idEncoded "user"."first_name",
fullName ==> "user"."last_name",
email "user"."email_address"
} FROM "accounts" AS "user"
} WHERE "user"."id" = 1

Looking at this query…


GraphQL is everywhere these days. From Facebook’s original usage of it to some more funky usages like databases, GraphQL is loved by so many developers that we are starting to use it in areas nobody would’ve thought of initially.

Every technology has its use cases for which it is ideal, for which it can work, for which it plain sucks, and everything in between. As developers, we want to pick the right tool for the job, which means understanding our use case and think about what tech might work best for it. …


And Why Union Types are Far from a Silver Bullet

This post is a snippet from Production Ready GraphQL. It is part of an update I’m working on for the schema design chapter in version 1.3. I decided to release it publicly as well because this side of abstract types is not talked about very much, and the subtle differences between interfaces and unions are not always easy to grasp. Hope you enjoy!

GraphQL Schema designers have in their toolbox two different abstract types they can choose from: Interfaces and Unions. While both of them allow us potentially return different concrete types for a single field, they work quite differently.


As GraphQL is gaining in popularity, misconceptions about how it works and what it provides are also growing. I demystify a lot of these misconceptions in detail in Production Ready GraphQL, but here’s a little top 3 list of misconceptions I see and hear around GraphQL these days.

Self-Documenting

REST: Requires documentation, GraphQL: Self-documenting

GraphQL is powered by a type system and this type system includes schema member descriptions. This is absolutely great and allows for API providers to describe their API in terms of fields, types, unions, etc. …


Should GraphQL queries be abstracted away?

Recently, a new GraphQL javascript client was released called gqless. The idea is really cool and clever: instead of writing GraphQL queries, client write typescript code in their application, and queries are generated at runtime.

https://gqless.dev/

gqless is a fundamentally new approach to a GraphQL client. It makes using your API enjoyable, by generating queries at runtime based upon the data your app consumes. (source: https://gqless.dev/docs/intro/what-and-why)

It aims to solve a few client side GraphQL issues, mostly the “double declaration problem”, a problem in which client developers need to first write a GraphQL query string, and then use a similar structure…


I’m really happy to announce that my book Production Ready GraphQL is now available!

The book contains a full overview of what is needed to build great GraphQL APIs:

  • Schema Design
  • Implementation Techniques
  • Performance & Monitoring
  • Security
  • Architecture
  • Documentation
  • Migrating from legacy APIs
  • A lot more: Everything I’ve learnt on building GraphQL APIs is in there!

With the book you may also get the Complete Package which contains:

  • Three extra guides (A schema design checklist you can keep close when building features, a full cheatsheet on making schema changes and evolving an API, and a few reviews of publicly accessible APIs to learn from existing APIs)
  • 4 interviews with amazing GraphQL community members including folks from Shopify, GitHub & More

Thanks for your support over the past few years!

https://twitter.com/__xuorig__/status/1242139226239569926


Coming out March 23rd!

I’m really happy to announce that my book Production Ready GraphQL is finally done and will be available on March 23rd!

This project started with a book I called “The Little Book of GraphQL Schema Design”, but quickly evolved into a bigger project. The book not only changed name but now covers much more than schema design. It contains a full overview of what is needed to build great GraphQL APIs:

  • Schema Design
  • Implementation Techniques
  • Performance & Monitoring
  • Security
  • Architecture
  • Documentation
  • Migrating from legacy APIs
  • A lot more: Everything I’ve learnt on building GraphQL APIs is in there!

With the…


How do you version GraphQL APIs? The most common answer you’ll get these days is “you don’t”. If you’re like me when I first read that, you might be a little anxious about maintaining a version-less API or a bit skeptical of the approach. In fact, not only is this a common answer, but it’s listed as a feature of GraphQL itself on graphql.org

graphql.org

When reading graphql.org, this may look like a feature being specific to GraphQL, but in fact, evolving APIs without versioning is something that has been recommended a lot for REST and HTTP APIs already. In fact…

Marc-André Giroux

#GraphQL Enthusiast, Speaker, Platform Interface Engineer @ GitHub 📖 Book is now available https://book.productionreadygraphql.com/

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store