apollo-link-rest

apollo-link-rest is an Apollo Link that lets Apollo Client talk to existing REST endpoints using ordinary GraphQL queries and mutations. Instead of standing up a GraphQL server or a schema-stitching gateway, you install the link alongside @apollo/client, tag fields with @rest(type, path) directives, and Apollo Client’s cache, hooks, and query language work directly against your REST responses.

It’s aimed at teams prototyping a GraphQL-first frontend before a backend migration, developers wiring third-party REST APIs into an Apollo Client app, and hybrid setups where some fields resolve from GraphQL and others from REST side-by-side.

What You Get

• A single RestLink instance that intercepts @rest-tagged fields in your GraphQL documents and issues the corresponding HTTP request
• Per-field configuration for HTTP method, path, endpoint, and per-request headers/credentials via directive arguments
• Automatic __typename insertion through a configurable typePatcher table so REST payloads work with Apollo’s normalized cache
• Field name normalization/denormalization to bridge REST’s snake_case or camelCase conventions with GraphQL naming
• Support for named endpoints, custom body serializers, and a pluggable customFetch for non-standard REST backends

Common Use Cases

• Prototyping a GraphQL API layer over an existing REST backend before committing to a full GraphQL server
• Incrementally migrating a REST-based frontend to GraphQL by mixing @rest and standard GraphQL fields in the same query
• Wrapping a third-party REST API that will never expose GraphQL so it can be queried through the same Apollo Client instance and cache as everything else
• Building admin or internal tools that need Apollo Client’s caching and hooks but only have REST services to call

Under The Hood

Architecture The core lives in a single module, src/restLink.ts (~1,400 lines), implementing RestLink as an ApolloLink subclass that intercepts GraphQL operations, walks the document AST to find @rest-tagged fields, and for each dispatches an HTTP request built from directive arguments (path, pathBuilder, bodyBuilder), then reinserts responses into the GraphQL response shape using a ported graphql-anywhere resolver (src/utils/graphql.ts) plus a typePatcher pass that recursively injects __typename. Endpoints, headers, serializers, and typePatchers resolve per-request with fallback to link-level Options set in the constructor. It is a layered but monolithic single-module design — one class handling directive parsing, request building, response resolution, and cache-shaping together — with only a small separate utils/graphql.ts isolating the AST-walking resolver logic ported from a deprecated graphql-anywhere package. Changing core directive parsing would ripple through the whole file since there is no separation between the directive-parsing, HTTP execution, and response-shaping layers.

Tech Stack Written in TypeScript (compiled with tsc targeting es5, bundled with Rollup, then browserify+uglify for a UMD script-tag build), with peer dependencies on @apollo/client >=3, graphql >=0.11, and qs >=6 (used for query-string serialization). DevDependencies pin an older toolchain (Apollo Client 3.0 beta, graphql 14.x, jest 23, ts-jest 23, TypeScript 3.x) reflecting the project’s 2017 origins, while the peerDependency ceiling is kept open-ended. Native fetch (or a caller-supplied customFetch) handles the HTTP layer. The build pipeline is tsc -> rollup (as a postbuild step) with a prebuild clean; CI on CircleCI currently only runs a gitleaks secret-scan job, with a legacy .travis.yml also present from an earlier CI setup.

Code Quality A single large test file, src/tests/restLink.ts (~4,200 lines, roughly 90 it() cases), covers directive parsing, endpoint resolution, typePatcher behavior, serializers, and error paths, run via jest + ts-jest. TypeScript is used throughout with declaration output enabled, though tsconfig sets noImplicitAny: false, so type coverage is present but not maximally strict. Error handling is explicit — a dedicated ServerError type carries the Response, status code, and result for failed HTTP calls rather than swallowing errors. Naming is consistent and heavily JSDoc-commented, with each Options field documenting its default and rationale. Prettier plus lint-staged enforce formatting on commit; no ESLint configuration is present, and the current CircleCI pipeline does not appear to run the test suite, leaving npm test as a local/manual gate rather than an enforced CI check.

API Design The library’s core idea — attaching a @rest(type, path, method, …) directive directly onto a GraphQL field — lets a REST response be queried with ordinary GraphQL syntax and land in Apollo Client’s normalized cache without a schema or resolver server. Ergonomics lean on a handful of escape hatches for edge cases: pathBuilder/bodyBuilder for dynamic requests, typePatcher tables for deep __typename injection, and per-request fieldName normalizer/denormalizer pairs for naming mismatches, all documented inline. Getting started only requires installing the package alongside @apollo/client, graphql, and qs, then adding one RestLink instance to the client’s link chain — low boilerplate for the common case. The tradeoff is that non-trivial REST shapes (nested typing, custom serialization) require learning several advanced, still-evolving callback APIs that the source comments themselves describe as not yet settled.