Documentation

Everything you need to build and operate a federated GraphQL API with feddi.

Overview

A tour of how feddi is put together: the two components that make up the system, how graphs and variants model your federated API, and how organizations group it all together.

Architecture

feddi has two components: the feddi Gateway that you self-host in your infrastructure, and the feddi Platform hosted at feddi.dev that manages schemas, composition, and analytics.

The feddi Gateway runs in your infrastructure alongside your subgraph services. It receives GraphQL requests from clients (web, mobile, AI agents), plans query execution across subgraphs, and returns unified responses. It polls the feddi Platform for schema updates and reports usage analytics.

The feddi Platform (feddi.dev) stores your subgraph schemas, composes them into a supergraph, detects breaking changes, tracks field-level usage, and serves persisted documents. You interact with it through the feddi CLI.

This separation means your data never passes through the feddi Platform: all GraphQL traffic stays within your infrastructure. The feddi Platform only handles metadata: schemas, analytics, and configuration.

Graphs & variants

A graph represents a federated GraphQL API. Each graph belongs to an organization and contains one or more variants.

Variants are independent environments of the same graph (e.g., production, staging, development). Each variant has its own set of subgraphs, composed supergraph, API keys, and usage analytics.

This lets you test schema changes in staging before promoting to production, with fully isolated composition and gateway configuration per variant.

Users and organizations

An organization groups graphs, members, keys, and billing. A user is a single account identified by email.

Users and organizations are a many-to-many relationship: a user can belong to several organizations at once (each with its own role), and an organization has many members. Graphs, subgraphs, keys, and persisted-document lists are all owned by the organization, not the user: switching organizations changes what you can see and manage.

Signing up creates an organization

When you sign up via /platform/signup without an invitation, feddi creates a new organization and makes you its Owner. If you were instead invited to an existing org, accepting the invitation joins you to that org with the role the inviter chose, and no new organization is created in that case. A user can repeat either flow to end up in multiple organizations.

Roles

Role is set per-membership, so the same user can be Owner in one org and Member in another.

Owner: Full control including org deletion and ownership transfer.
Admin: Can invite/remove members, manage graphs, create keys.
Member: Basic read access and schema publishing.

Member limits

The Free tier supports up to 10 members per organization (including pending invitations). Upgrade to Enterprise for unlimited members.

Invitations

Owners and Admins can invite Members by email. Invitations expire after 7 days and can be resent or revoked. Invited users who don't yet have a feddi account go through a one-click accept flow that creates the account and the membership in a single step.

GraphQL Federation spec

feddi implements the open GraphQL Federation (Composite Schemas) specification maintained under the GraphQL Foundation. Subgraph schemas use the standard federation directives (@lookup, @external, @requires, @provides, @shareable, etc.) and the platform composes them into a supergraph following the spec's rules.

Because the wire format and subgraph contract are standard, feddi interoperates with any GraphQL server framework. You aren't locked into a feddi-specific runtime on the subgraph side.

Getting Started

feddi lets you compose multiple GraphQL services into a single, unified API. Each service (subgraph) owns its slice of the schema, and feddi composes them into a supergraph.

1. Sign up and create an organization

Create an account at feddi.dev/platform/signup. Each account belongs to an organization where you manage graphs, members, and API keys.

2. Install the feddi CLI

Download the feddi CLI from the Downloads page, then authenticate:

3. Create a graph and variant

4. Create and publish a subgraph

feddi composes your subgraph schemas into a supergraph automatically and validates compatibility.

5. Start the feddi Gateway

Download the feddi Gateway binary from the Downloads page, create a feddi-gateway.yml with your graph variant key, and start it. The feddi Gateway polls the feddi Platform for schema updates.

feddi Gateway

The feddi Gateway is a standalone Java application that receives GraphQL requests from clients, plans query execution across your subgraphs, and returns unified responses.

It is an open-source project (Apache License 2.0) hosted at github.com/feddi-dev/feddi-gateway. The feddi Gateway works best alongside the feddi Platform (for schema polling, usage reporting, persisted-document resolution, and managed credentials), but does not depend on it: you can run the feddi Gateway with a locally-supplied supergraph SDL and no platform connection at all. See the gateway README for the standalone usage modes.

Get started

Download a prebuilt feddi Gateway distribution bundled with the feddi-platform extension from the Downloads page. The archive contains the feddi Gateway JAR, launcher scripts for Linux, macOS, and Windows, and a sample feddi-gateway.yml that you can edit in place to point at your graph variant key.

Configuration reference

All runtime configuration lives in a single feddi-gateway.yml in the working directory. A minimal platform-connected example:

Core gateway options (top-level keys)

Platform extension (extensions.feddi.*)

Only active when the feddi-platform-extensions JAR is present in libs/ (the prebuilt distribution includes it).

Launcher environment variables

Consumed by the bin/feddi-gateway launcher script in the prebuilt distribution. They do not affect java -jar feddi-gateway.jar invoked directly.

Subgraphs

A subgraph is a named GraphQL service in a variant. Creating a subgraph only creates that identity; it does not publish a schema or configure a gateway endpoint.

The subgraph config is JSON that is published alongside the schema SDL. Today the gateway reads the url field to decide where to send requests for that subgraph. The gateway always reads the SDL and config from the latest successful publish event, not from an independently editable subgraph setting.

Publishing schemas

The first publish attempt for a subgraph must include valid JSON config. feddi composes the submitted SDL with the latest successful SDL and config from the other subgraphs in the variant. If composition succeeds, the new supergraph and the submitted SDL/config snapshot become visible to the feddi Gateway on its next poll.

After a subgraph has a successful publish, later schema-only publishes can omit --config. In that case feddi reuses the config from the latest successful publish for that subgraph.

Updating subgraph config

To change where the gateway routes a subgraph, publish again with --config. If the SDL is unchanged, pass the same schema file with the new config. A failed publish does not replace the gateway-visible SDL or config; the gateway continues using the latest successful publish.

Schema checks

Before publishing, you can run a schema check to verify composition and detect breaking changes without persisting anything. Checks can use an explicit config, or omit it after the subgraph already has a successful publish.

Breaking change detection

Both publish and check detect breaking changes by comparing the old and new supergraph schemas. Breaking changes (field removals, type changes, nullability changes) are rejected by default.

Override flags

Two mutually exclusive flags allow overriding:

Persisted Documents

Persisted document lists (PDLs) let you pre-register GraphQL operations so clients can send a hash instead of the full query string. This reduces payload size and enables safelisting.

Create and link a PDL

Publish documents

The SHA-256 hash is computed server-side. Publishing is idempotent: duplicate documents are ignored.

Publishing from CI

A CLI session authenticated as an Admin or Owner (via personal access token) can publish documents, but in practice you don't want your frontend-build pipeline holding Admin credentials. For that, create a persisted-document publish key: a graph-scoped credential that is allowed to publish documents to any PDL on its graph and nothing else. It cannot create/link/delete PDLs, publish subgraphs, or read schemas.

Typical flow, run once by an Owner or Admin:

The command prints a token prefixed with fddi_pdpk_. Store it as a secret in your CI (GitHub Actions secret, etc.), then in the build job:

Rotate by issuing a new key and feddi pd-publish-key revoke <old-key-id>.

Wire protocol

The feddi Gateway supports the Apollo APQ protocol by default. Clients send extensions.persistedQuery.sha256Hash instead of a query string. The protocol is customizable via the PersistedDocumentProtocol extension point.

Usage & Analytics

The feddi Gateway reports field-level usage data to the feddi Platform. This data powers analytics dashboards, breaking change detection, and monthly usage limits.

What's tracked

For each operation, the feddi Gateway reports its name, type (QUERY, MUTATION, or SUBSCRIPTION), operation hash, selected field coordinates, input usage coordinates, client name and version, duration, and errors. Usage commands read aggregated rollups, so very recent traffic only appears after the next rollup.

Output field usage and input usage are tracked separately. Field coordinates identify the output fields the operation selected. Input usage coordinates identify the arguments, input object fields, directives, and directive arguments the operation referenced. The two use distinct formats — see Coordinate formats.

Client breakdowns

Field, input, and operation usage summaries include a client breakdown. By default, rows are grouped by client name and version. Use --client-aggregation client-operation-name to split each client by operation name, or --client-aggregation client-operation-hash to split by operation hash. Operation-name aggregation sums different hashes for the same client and operation name; operation-hash aggregation keeps hashes separate and also returns the operation name when available.

The GraphQL API exposes the same options through the clientAggregation argument on fieldUsage, inputUsage, and operationUsage: CLIENT, CLIENT_OPERATION_NAME, or CLIENT_OPERATION_HASH.

Client breakdowns are limited to the top 100 entries by request count. Human-readable CLI output prints a truncation note when more clients exist; JSON output and GraphQL responses expose clientsTruncated: true.

Coordinate formats

Every usage record is keyed by a coordinate. Output field usage uses one format; input usage spans four kinds, selected or filtered with the --kind flag on feddi usage inputs, feddi usage, and feddi usage last-used.

Coordinates containing (, ), or @ must be quoted in shell commands, for example 'Query.user(id:)' or '@include(if:)'.

Monthly limits (Free tier)

Each variant has a monthly limit of 1,000,000 requests and 250,000 usage buckets. When limits are reached, the feddi Gateway continues serving requests but stops reporting usage data. Upgrade to Enterprise for unlimited operations.

CLI commands

The CLI exposes three families of usage commands. Each family is summarised below with example invocations; full per-command flag references are in CLI Reference → Usage analytics.

Field usage

Reports request count, error count, average duration, last-used time, and client breakdown per field coordinate.

Input usage

Reports which arguments, input object fields, directives, and directive arguments appeared in registered operations. feddi usage inputs filters by input coordinate kind; feddi usage and feddi usage last-used use --kind to pick which family of coordinate to look up.

Operation usage

Reports request count, error count, average duration, clients, selected fields, and input usage coordinates per operation.

Keys & Authentication

Personal access tokens

PATs authenticate your CLI and API requests as your user account. Create them in Settings → Access Tokens.

Graph variant keys

Graph variant keys authenticate the feddi Gateway. They're scoped to a variant and grant access to all subgraphs within it. The feddi Gateway uses the graph variant key to poll for schema updates and report usage.

Subgraph keys

Subgraph keys are scoped to specific subgraphs within a variant. Use them in CI/CD pipelines for publishing schemas with least-privilege access.

Persisted-document publish keys

Graph-scoped keys that authorize one thing: publishing documents to any PDL belonging to the target graph. They cannot create, link, or delete PDLs, publish subgraphs, or read schemas, and are designed for frontend-build CI pipelines that need to ship a persisted-query manifest on every deploy without exposing broader privileges.

CLI Reference

Complete command reference. All commands support --json for machine-readable output.

Automatic updates

The feddi CLI checks /releases/latest/manifest.json once an hour at startup and silently upgrades itself when a newer build is available. The check fetches a small JSON (a few hundred bytes), verifies the new tarball's SHA-256 against the manifest before any filesystem write, and swaps the binary atomically. A one-line confirmation is printed to stderr after a successful update. A failed check (network timeout, checksum mismatch, missing write permission) never aborts the command you ran.

The check is automatically skipped in environments where an update would be disruptive: when CI=true, when automatic updates are explicitly disabled, and when the feddi CLI is a source build (feddi version reports dev).

To opt out explicitly:

Set FEDDI_DEBUG=1 to see why a check was skipped or why one failed.

Authentication

Graphs

Variants

Subgraphs

Persisted document lists

Keys

Usage analytics

All usage commands support the global --json flag. List commands support Relay-style pagination with --first, --after, --last, and --before; for list commands, --last is an item count. Coordinate detail commands use --last <duration> to restrict results to a recent window, with values like 1h, 7d, 4w, or 6mo.

Commands that include client breakdowns support --client-aggregation <client|client-operation-name|client-operation-hash>. Client breakdowns return the top 100 entries; clientsTruncated in JSON output indicates that additional client rows were omitted.

Organizations & members

Miscellaneous