skills/docs/api-stack/api/api-graphql-apollo/README.md

@suaveplan/api-graphql-apollo — Apollo Server GraphQL engine adapter for the Suaveplan API plugin system. Implements the GraphqlEngine contract from @suaveplan/api-graphql and passes runGraphqlEngineConformance with the same invariants as the Yoga sibling. Adds Apollo-specific persisted-query manifest support, optional Apollo Studio usage reporting, depth + complexity guards, federated multi-plugin schema merging, per-request DataLoader scoping, engine-agnostic OTel instruments, and graphql-ws subscription bridging.

Stage-7 Apollo Server GraphQL engine adapter for the Suaveplan API plugin system. Implements the GraphqlEngine contract from @suaveplan/api-graphql and passes the conformance suite alongside the Yoga sibling — switching engines is a host-config change.

Documentation tree

• http — endpoints/http mounts the two HTTP endpoints every GraphQL adapter must expose: POST /graphql for operation dispatc…
• ui-proxy — endpoints/ui-proxy mounts the /graphql/ui endpoint. The Apollo engine never embeds Apollo's landing page — UI is op…
• engine — ApolloGraphqlEngine is the concrete Apollo Server implementation of the @suaveplan/api-graphql engine contract. It…
  • apollo-engine — ApolloGraphqlEngine is the concrete Apollo Server implementation of the @suaveplan/api-graphql engine contract. It…
• error-codes — error-codes defines the stable GRAPHQL_APOLLO.* namespace plus the GraphqlApolloError class consumed by every oth…
  • error-codes — error-codes defines the stable GRAPHQL_APOLLO.* namespace plus the GraphqlApolloError class consumed by every oth…
• federation — federation is the engine's facade over the canonical mergeSdl function from @suaveplan/api-graphql. Apollo doesn'…
  • federation — federation is the engine's facade over the canonical mergeSdl function from @suaveplan/api-graphql. Apollo doesn'…
• guards — depth-and-complexity walks a parsed DocumentNode and computes two coarse static metrics — the maximum selection-set…
  • depth-and-complexity — depth-and-complexity walks a parsed DocumentNode and computes two coarse static metrics — the maximum selection-set…
• instruments — instruments owns the five OTel instrument names emitted by every GraphQL engine adapter in the foundation. Both `api-…
  • instruments — instruments owns the five OTel instrument names emitted by every GraphQL engine adapter in the foundation. Both `api-…
• loaders — loaders defines the per-request DataLoader scope the engine creates around every incoming GraphQL operation. Two conc…
  • loaders — loaders defines the per-request DataLoader scope the engine creates around every incoming GraphQL operation. Two conc…
• options — options owns the Zod-validated configuration surface accepted by createApolloGraphqlEngine. The schema mirrors the…
  • options — options owns the Zod-validated configuration surface accepted by createApolloGraphqlEngine. The schema mirrors the…
• persisted-queries — persisted-queries implements Apollo's persisted-query manifest lookup — the ability for clients to send { id } in p…
  • persisted-queries — persisted-queries implements Apollo's persisted-query manifest lookup — the ability for clients to send { id } in p…
• studio-reporting — studio-reporting materialises the configuration descriptor consumed by the engine when an operator opts in to Apollo…
  • studio-reporting — studio-reporting materialises the configuration descriptor consumed by the engine when an operator opts in to Apollo…
• subscriptions — subscriptions runs a GraphQL subscription document against a wired schema, returning the `AsyncIterable<ExecutionResu…
  • subscriptions — subscriptions runs a GraphQL subscription document against a wired schema, returning the `AsyncIterable<ExecutionResu…
• testing — testing/conformance is the re-export of runGraphqlEngineConformance from @suaveplan/api-graphql/testing, pre-boun…
  • conformance — testing/conformance is the re-export of runGraphqlEngineConformance from @suaveplan/api-graphql/testing, pre-boun…

When to choose Apollo over Yoga

• You want Apollo Studio usage reporting (studioReporting option).
• You ship persisted-query manifests built by Apollo's CLI / Rover.
• Your team already runs Apollo's federation tooling in adjacent services.
• You need Apollo's plugin ecosystem (cost analyser, request coalescer, custom cache plugin, …).

Otherwise, Yoga is the faster default — fewer allocations per request, slimmer dependency closure.

Modules

• engine — ApolloGraphqlEngine, createApolloGraphqlEngine.
• options — Zod-validated ApolloGraphqlOptions schema.
• error-codes — GRAPHQL_APOLLO.* registry + GraphqlApolloError.
• instruments — engine-agnostic graphql.* OTel surface.
• guards — depth + complexity rejection helpers.
• persisted-queries — APQ manifest loader.
• studio-reporting — Apollo Studio descriptor bridge.
• subscriptions — graphql-ws runner.
• loaders — per-request DataLoader scope.
• federation — mergeSdl passthrough.
• endpoints — HTTP + UI proxy mounts.
• testing — runApolloConformance re-export.

Status

Original. Owned by the api-stack super-category. Passes the abstract conformance harness with the same invariants Yoga satisfies — see src/engine/apollo-engine.spec-conformance.test.ts.