GraphQL protocols are a set of conventions using GraphQL Schema Definition Language (SDL) that make it easy to describe GraphQL API’s for federated services allowing implementations to be interchangable and interoperable.

I know this sounds pretty out there so lets zoom in on its exact usecase and origins.

Lets start with some clarification of terms.

A federation is a group of computing or network providers agreeing upon standards of operation in a collective fashion. The aim of it is to make functionality interchangeable or interoperable.

Think of Mastodon that uses federation to create a collective of instances and aggregate data (messages, photos, videos) from all instances to show in your federated timeline. Another example is making it possible to make things interchangable like having the single command line interface application to spin up virtual machines at Amazon or at Azure just by switching an endpoint url. Or using the same messenger app to talk to different chat services like Slack or Discourse.

In order to make this possible, both the providers need to have same API standard so the client can talk to it uniformly using a protocol. To make it more concrete. Lets say you want to launch a new machine on either Amazon or Azure, you’d need to send a request to provider the with specific payload at a certain url. If this doesn’t exactly match the exact format it would explode.

The first step of making this possible is making an agreement on how these servers communicate. Usually this is put into a lengthy fancy spec like the one for Activitypub which describes the calls and the rules of engagement.

This works to some extend but is eleborate, hard to read and quite difficult to implement for a impatient geek like me. Additionally, from federation to federation protocol things arent so uniform. I.e. different form of REST calls or maybe no rest at all. Different ways of describing types and usually no code generation or libraries. All in all, its pretty difficult and a pain to implement this properly if we truly want to move to a federated web.

In my opinion, protocols should be super simple to design, to talk about, understand and implement in order to really promote adoption and gain traction for an interchangable web where we not only have activity pub but a whole set of protocols to our disposal.

And this is where GraphQL protocols come to play.

With GraphQL protocols, ensuring that an API adheres to an interface or protocol (at least from the API definition side) is as easy as dropping in an SDL file and putting an interface on your mutation, query or viewer type.

Imagine this Postbox Protocol for sending messages (this file is what you’d get from your vendor).

# The type you need for your protocol
type Message {
  message: String!
}

# Add this to your query type
interface Postbox {
  messages: [Message!]!
}

# Add this to your mutation type
interface PostboxMutatations {
  postMessage(message: String!): Message!
}

You can simply paste this in your existing SDL. Instead of pasting, the protocol can also be installed using NPM or RubyGems, which allows you for updating your schemas as well as following semver versioning conventions. Additionally it will provide you the stubs that you’d need to implement the API.

You’d then need to extend your query and mutation type. If the Protocol would have realtime subscriptions you’d also need to extend the subscription type.

type Query implements Postbox {
  messages: [Message!]!
}

type Mutation implements PostboxMutatations {
  sendMessage(message: String!): Message!
}

And tada! You’re done adhering to the Postbox protocol 🚀 Ofcourse you still need to write the actual implementation but the spec is done!

You can now use your standard GraphQL tools in order to generate a client for it.

Now the next step is to distribute your protocol so that others can implement it or give feedback on. Thats nothing more than just raising a pr to the graphql-protocols repo in order to announce it.

Declarative, explicit, uniform and typed with GraphQL

GraphQL has a rich type system. Easy to introspect for humans and machines using GraphiQL. Easy to query and contract based. There is tons of tooling for it that allows us to generate code for it too.

It has clear points on how to do mutations, queries and even realtime subscriptions, is explicit and leaves not much wiggle room (which is good).

Sharable, discussable, easy to read and understand with SDL

The SDL is a GraphQL standard and its the easiest way to read how the GraphQL API would work. The SDL also allows for comments that can clarify how the functional rules of the API work. Reading SDL should be enough to get the API, it should be small and declarative. It’s just a single file, easy to drop in and its both human readable and machine interpretable.

Why not traditional documents

Pain to read usually. Not much tooling to generate code for. No introspection. Makes me want to cry 😢

Hey you 👋. Want to stay up to date?

Would you like to stay up to date on upcoming learn-togethers or events? Subscribe here! I'll only use your email to keep u up to date on new learnings and coding tips. It wont be shared! Feel free to unsubscribe anytime!