apollo-link-rest: Querying REST Endpoints With GraphQL Syntax

A link that pretends a REST endpoint is a GraphQL server

apollo-link-rest is an Apollo Link whose purpose is to let you try out GraphQL without a full server. The stated use cases are prototyping, working with third-party services that do not have a GraphQL endpoint, and making a transition from REST to GraphQL. The mechanism is that the link intercepts a GraphQL operation and turns it into an HTTP request against a REST URL, then maps the response back into the shape the query asked for. The value is on the client side of the boundary. Your components and hooks keep using a GraphQL document and a normalised cache, while the thing on the other end of the wire is an ordinary JSON endpoint that already exists and already has behaviour you depend on. Nothing about the REST service has to change.

How a GraphQL query becomes a REST path

The basic example makes the shape clear. A RestLink is created with a uri, an ApolloClient is configured with that link and the default in-memory cache, and the query uses a directive to say what to fetch.

import { RestLink } from "apollo-link-rest";
// Other necessary imports...

// Create a RestLink for the REST API
// If you are using multiple link types, restLink should go before httpLink,
// as httpLink will swallow any calls that should be routed through rest!
const restLink = new RestLink({
  uri: 'https://swapi.co/api/',
});

The query then names the REST resource in the directive, with a type and a path, and selects only the fields it needs.

const query = gql`
  query luke {
    person @rest(type: "Person", path: "people/1/") {
      name
    }
  }
`;

So the REST path is derived from the type and the path in the directive and appended to the base uri, and the selection set tells the link which properties to keep out of the response. The one structural warning in the sample is about link ordering, and it is the single most likely thing to get wrong.

Link ordering decides who sees the request

The comment in the example says it directly: if you are using multiple link types, restLink should go before httpLink, as httpLink will swallow any calls that should be routed through rest. This is a consequence of how Apollo links are chained. Each link in the chain gets a chance to handle the operation, and a link further down the chain, once it has decided to handle the request, takes it out of circulation. The HTTP link does exactly that for every operation, so if it sits above the REST link in the chain, the REST link never sees the operation and every query goes out as a normal GraphQL request to your GraphQL endpoint. The consequence of getting it wrong is quiet rather than loud: no error, just results that come from the wrong place, or an empty response. The same reasoning applies to any other link you mix in, and it is worth checking the order whenever you add one.

The options that shape the request

RestLink takes an options object with a small set of keys. The `uri` is a string endpoint and is optional when `endpoints` supplies a default. The `endpoints` key is either a root endpoint to apply paths to or a map of endpoints. `customFetch` is a custom fetch used to handle the REST calls, which is the hook for a non-browser environment, a polyfill or an instrumented client. `headers` is an object of values sent as headers on the request, and `credentials` is a string naming the credentials policy for the fetch call. `fieldNameNormalizer` is a function that takes the response field name and converts it into a GraphQL compliant name, which is the piece that makes real-world payloads usable, since REST APIs routinely return keys with spaces, dashes or capitalisation that are not valid GraphQL field names. The headers and credentials can also be supplied per request through the operation context, which the documentation describes as a separate context section.

Installing the link with its peer dependencies

The package installs with its peer dependencies in one command.

npm install apollo-link-rest @apollo/client graphql qs --save
or
yarn add apollo-link-rest @apollo/client graphql qs

`@apollo/client`, `graphql` and `qs` are peer dependencies needed by apollo-link-rest, which is worth noting because peer dependencies are not installed automatically in the way regular dependencies are, and a mismatch here surfaces as a runtime error rather than a build error. The `qs` dependency is there for query string construction, which is what the path and parameters in the directive turn into. Two release candidates exist for the current line, v0.10.0-rc.1 and v0.10.0-rc.2, both from November 2025, both described as Apollo Client v4 with dependency updates, and the previous stable release is v0.9.0 from November 2022. The last push was on 2026-10-21, so the work is current even though the tagged releases are not.

Working on the link yourself

The project uses TypeScript to bring static types to JavaScript and Jest for testing, and the contributing steps are the familiar ones.

npm install # or `yarn`

npm test # or `yarn test` to run tests
npm test -- --watch # run tests in watch mode

npm run check-types # or `yarn check-types` to check TypeScript types

To try the library inside another project without publishing it, there is a link workflow.

npm link

# in the project you want to run this in
npm link apollo-link-rest

The package manifest shows the rest of the machinery. The build is tsc for the types and a rollup bundle for the distribution, there is a separate browser build using browserify with uglifyjs for minification, and a bundlesize check on the filesize script, which is a sensible thing to enforce in a library that runs in the browser. Linting is prettier, there is a codecov upload step, a dangerfile for pull request checks, renovate for dependency updates, and a set of scripts that pull the documentation into the repository and push it back out, which is how the docs on the Apollo site stay in step with the code.

Community maintained, and what that means for you

The readme opens with a warning that the library is under active development, and it explains what that means: the project is maintained by Apollo community members and not an Apollo GraphQL maintained library. Progress is tracked in the issues and in a design document under designs/, and the maintainers ask for help with docs and testing. That is a fair description of the state and it is the first thing to weigh. A community-maintained link in the Apollo ecosystem is a reasonable thing to prototype with, but it is not the same as a component with a support commitment behind it, and the release naming reflects that, with the current line still in release candidates. The repository also carries a schema.graphql file at the top level, a CI configuration through CircleCI and Travis files, and an examples directory with simple, advanced and typescript variants, each of which is mirrored as a CodeSandbox linked from the readme, so you can see the link working before you install anything.

Editorial conclusion

apollo-link-rest fits a team that wants to try GraphQL against a REST backend, or one part-way through a REST to GraphQL migration and wants the frontend to speak GraphQL while the server catches up. It is the wrong choice if you need writes to be transactional, since a REST endpoint behind a query has no GraphQL mutation semantics, and the wrong choice for production use if you need the guarantees of a real schema. Before you build on it, check the link ordering against your other links, because a misordered link will swallow the calls meant for REST.

Frequently asked questions

Official sources

1. apollographql/apollo-link-rest on GitHub
2. Issues
3. License: MIT
4. README
5. Releases