--- title: "Federation instead of a hand-written gateway" date: "2020-02-01T06:00:00.000Z" categories: "Architecture" canonical: "https://xraph.com/writing/federation-over-a-hand-written-gateway" --- # Abstract A stitched GraphQL gateway is a second schema somebody has to maintain. Federation moves that declaration into the services, and the trade is real but favourable. ## The problem with stitching The first version of Ultimate Backend used schema stitching. A gateway service imported each downstream schema, renamed types where they collided, and declared the links between them. It worked, and the gateway became the most edited file in the repository. Every new field on a service required a corresponding edit in the gateway. The two lived in different places, were owned by different concerns, and were deployed on different cadences. They agreed on the day they were written and drifted afterwards, which is the same failure that turns up wherever one system declares facts about another [3]. ## What federation changes Under federation, each service declares which types it owns and which types it extends. The gateway composes a supergraph from those declarations at runtime. Nobody writes the composed schema, and nobody maintains it. A service that adds a field adds it in its own repository, and the field appears in the composed graph on the next composition. A service that goes away takes its fields with it. That is the property worth having, and it is the same property that later made me build a manifest protocol for HTTP gateways: the service is the only thing that reliably knows its own surface. ## The costs, which are not small Federation is more constrained than stitching. Entity resolution requires a key on every shared type, and the key has to be resolvable by every service that extends it. That pushes design decisions into the schema that used to live in resolver code, and some of those decisions are uncomfortable. Debugging is harder. A query that fails may fail in composition, in the gateway's planning, or in one of several services, and the error you see is often the last of those rather than the first. Performance requires attention. The gateway plans a query into a sequence of subqueries, and a badly shaped schema produces a plan with more round trips than you expect. This is visible only under load, which means it is usually visible only in production. ## When it is not worth it With two services and one team, stitching is fine and federation is ceremony. The value appears when the number of services exceeds the number of people who can hold the whole schema in their head, which in my experience is around five or six services. The general form of this judgement is the one the microservices literature keeps arriving at [1] [2]. Distribution buys independence and charges coordination. Below a certain size you are paying without buying anything. # References 1. James Lewis, Martin Fowler, "Microservices: A Definition of This New Architectural Term", martinfowler.com, 2014 2. Sam Newman, "Building Microservices: Designing Fine-Grained Systems", O'Reilly Media, 2nd edition, 2021 3. D. L. Parnas, "On the Criteria To Be Used in Decomposing Systems into Modules", Communications of the ACM, vol. 15, no. 12, pp. 1053-1058, 1972 --- *Unpublished draft. Not peer reviewed and not submitted to a venue.*