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 interchangeable and inter-operable.

I know this sounds pretty out there so lets zoom in on its exact use-case 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 inter-operable.

Think of Mastodon, a distributed twitter clone, 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 interchangeable 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. Or in the case of GraphQL, both endpoints would have the exact same type definition and the same mutations, queries.

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 elaborate, hard to read and quite difficult to implement for a impatient geek like me. Additionally, from federation to federation protocol things aren’t 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 interchangeable 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 you’re done!

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
extend type Query {
  messages: [Message!]!
}

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

You can simply paste this in your existing SDL, or 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 if you wish to do so.

And tada! You’re done adhering to the Postbox protocol! Of course 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. That’s 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).

Shareable, 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 for protocols

Pain to read usually. Not much tooling to generate code for. No introspection. Just in general a bad idea.

Whats next?

So now that we can talk with each other, the next step is to authenticate us in a federated way. So head Oliver and read about our first protocol on how to request API tokens in the Request API tokens easily with the GraphQL token request protocol