{"id":22487547,"url":"https://github.com/graphql-protocols/graphql-protocols","last_synced_at":"2025-08-02T20:30:54.915Z","repository":{"id":134027646,"uuid":"158684696","full_name":"graphql-protocols/graphql-protocols","owner":"graphql-protocols","description":"Common GraphQL interfaces as protocols for federation and interchangeability","archived":false,"fork":false,"pushed_at":"2019-07-01T08:37:33.000Z","size":13,"stargazers_count":11,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T09:05:02.792Z","etag":null,"topics":["graphql","graphql-protocols","graphql-schema","microservices","sdl","services"],"latest_commit_sha":null,"homepage":"http://emilebosch.com/2019/06/27/why-we-need-graphql-protocols/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graphql-protocols.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-22T10:48:59.000Z","updated_at":"2024-09-06T08:50:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"c1ed9c87-88e9-4ff5-b795-8fbe87120df8","html_url":"https://github.com/graphql-protocols/graphql-protocols","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/graphql-protocols/graphql-protocols","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-protocols%2Fgraphql-protocols","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-protocols%2Fgraphql-protocols/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-protocols%2Fgraphql-protocols/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-protocols%2Fgraphql-protocols/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphql-protocols","download_url":"https://codeload.github.com/graphql-protocols/graphql-protocols/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-protocols%2Fgraphql-protocols/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268448362,"owners_count":24252019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphql","graphql-protocols","graphql-schema","microservices","sdl","services"],"created_at":"2024-12-06T17:16:50.476Z","updated_at":"2025-08-02T20:30:54.893Z","avatar_url":"https://github.com/graphql-protocols.png","language":null,"funding_links":[],"categories":["Others"],"sub_categories":[],"readme":"# GraphQL Protocols\n\n\u003e WARNING: We're working on this 💪. For discussion purposes only at this moment.\n\n\nThe simplest way to describe protocols for peer-to-peer and client to server communication via GraphQL interfaces, built for the [social](https://github.com/graphql-protocols/social) protocol family. \n\n- 👉 [Read the introduction post here](http://emilebosch.com/2019/06/27/why-we-need-graphql-protocols/)\n- 👉 [Check out a Sinatra sample](https://github.com/graphql-protocols/graphql-protocols-sinatra-sample) if you're in a hurry.\n\n![GraphiQL](https://raw.githubusercontent.com/graphql-protocols/graphql-protocols-sinatra-sample/master/images/graphiql.jpg)\n\n## What is this?\n\nBasically, a repository of common GraphQL service interfaces for everyone to implement. Think 'services' as WSDL that defines how servers or servers-to-client can communicate to each other via a common GraphQL interface. The core idea is that a server can simply request what protocols (interfaces) a GraphQL server implements and can start communicating with that server if it supports that queried protocol.\n\n## What does this solve?\n\nIt solves the rules of engagement and lack of standardization on how server-to-server or clients should talk to eachother and therefore enhancing interoperability for the open web. It makes data and operations on it _interchangable_.\n\nAn example; there are 20 domain name registrars where you can buy domain names and automating registering domains would require implementing 20 specific APIs. What if there would be _just_ one simple interface that allows you to talk with all these registars? \n\nWith the help of GraphQL protocols, one could define a single interface that all registrars would need to implement. This way you could build a registration client allowing to register at those vendors easily. That's the aim of GraphQL protocols. Making it easy to build interfaces for distributed services.\n\nThe same goes for an _notifcation_ service. You define the protocol and the resulting notification implementation can differ from Slack to email as long as you adhere to the GraphQL SDL protocol, the resulting consumers won't break either.\n\nSome other usecases where GraphQL protocols would shine:\n\n- A federation protocol for peer-to-peer or federated applications, think of federation applications such as Mastodon or Pixelfed.\n- Peer to peer communication between servers.\n- Interoperability between vendors, having a GraphQL protocol for spawning machines at Amazon the same way as at Digital Ocean.\n\n## Why GraphQL for protocols\n\nGraphQL is a simple concept for humans and machines. It is elegant and the SDL is descriptive, inuitive, shareable, and easy to  and implement.\n\n- Simple introspection of what interfaces/protocols an endpoint implements by just viewing the query or mutation type.\n- Makes humans and machines both happy ❤️\n- Composable. Simple to compose and extend.\n- A dead simple principle, if you know GraphQL you know it already .\n\nAnd of course the benefits of GraphQL itself, such as:\n- Self-documenting\n- Strongly typed\n- Supports deprecation and versioning\n- The whole GraphQL ecosystem such as client description.\n\n## Current draft protocols\n\nAll of the protocols are currently in DRAFT state and used as input for discussion.\n\n- [Request Tokens](draft/token-request.md) - A self-service way of retrieving an API token from a service for communication. With this protocol you can identify yourself to the service and start using other protocols (APIs) on that service if they require authentication.\n- [Postbox](draft/postbox.md) - Send messages to a service / site\n\n## How does it work technically?\n\nThe protocols are just _Plain Old GraphQL Interfaces_ written in [SDL](https://graphql.org/learn/schema/). Servers and clients need to implement these interfaces and types to talk with each other. GraphQL protocols are a _best practice pattern_ rather than an actual technical solution.\n\nUsually, such a protocol exists out of a couple of parts defined in the GraphQL schema definition. For example, let's say you have a bunch of servers that send messages to each other. By connecting to a server that supports this protocol, you can easily send a message to the owner of that protocol.\n\nThe types you need for your service (You will share this file with your implementers):\n\n```graphql\n\n# The type you need for your service\ntype Message {\n  message: String\n}\n\n# The query interface\ninterface Postbox {\n  messages: [Message]\n}\n\n# The mutation interface\ninterface PostboxMutatations {\n  postMessage(message: String): Message\n}\n```\n\nThen you need to hook them up to your query type.\n\nAdd to your query type:\n\n```graphql\ntype Query implements Postbox\n```\n\nAdd to your mutation types:\n\n```graphql\ntype Mutation implements PostboxMutatations\n```\n\nAnd that's it. The idea is that the protocol part is _reusable_. And that other implementers only need to implement your interface SDL for clients to talk to.\n\n## Protocol writing best practices\n\nThis will help you building protocols that are easy to maintain.\n\n### Keep protocols small\n\nKeep your protocols as easy and small as possible. The chances that complicated protocols will get implemented are quite small. The easier to implement, the higher chances of adoption.\n\n### Write it for humans\n\n- Make it conversational in terms of naming for mutations and fields\n- Make it easy to implement with just GraphiQL. If its painful to use the protocol in GraphiQL it will be hard to implement too.\n- Keep it intuitive in terms of naming and flow\n- Communicate as if you're communicating to a human\n\n### Adhere to GraphQL conventions\n\n- Things under `viewer` should be tied to the `viewer` (i.e current authenticated user)\n- Mutations under mutations field\n- Things that are public available for al consumers outside the scope of `viewer`\n\n### Make it resilient\n\n- Think that your service might not be available so make things nullable that could be nullable in an outage.\n\n## Want to make your protocol?\n\nFork this repo, use the [template](template.md) and raise a PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphql-protocols%2Fgraphql-protocols","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphql-protocols%2Fgraphql-protocols","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphql-protocols%2Fgraphql-protocols/lists"}