apollo-link-rest

What is apollo-link-rest?

The apollo-link-rest package allows you to integrate REST endpoints into your Apollo Client setup. It provides a way to fetch data from RESTful APIs and use it within your GraphQL queries, making it easier to transition from REST to GraphQL or to use both in a hybrid approach.

What are apollo-link-rest's main functionalities?

Basic REST Query

This code demonstrates how to set up a basic Apollo Client with a RestLink to fetch data from a REST endpoint. The query fetches user data from the '/user' endpoint.

const { ApolloClient, InMemoryCache } = require('@apollo/client');
const { RestLink } = require('apollo-link-rest');

const restLink = new RestLink({ uri: 'https://api.example.com/' });

const client = new ApolloClient({
  link: restLink,
  cache: new InMemoryCache()
});

client.query({
  query: gql`
    query GetUser {
      user @rest(type: "User", path: "/user") {
        id
        name
      }
    }
  `
}).then(response => console.log(response));

Handling POST Requests

This code demonstrates how to handle POST requests using apollo-link-rest. It sends a POST request to the '/user' endpoint to create a new user.

client.mutate({
  mutation: gql`
    mutation CreateUser($input: CreateUserInput!) {
      createUser(input: $input) @rest(type: "User", path: "/user", method: "POST") {
        id
        name
      }
    }
  `,
  variables: {
    input: {
      name: 'New User'
    }
  }
}).then(response => console.log(response));

Custom Headers

This code shows how to set custom headers for your REST requests, such as an Authorization header for authenticated requests.

const restLink = new RestLink({
  uri: 'https://api.example.com/',
  headers: {
    Authorization: 'Bearer YOUR_TOKEN'
  }
});

Other packages similar to apollo-link-rest

apollo-link-http

apollo-link-http is used to connect Apollo Client to a GraphQL server over HTTP. Unlike apollo-link-rest, it is specifically designed for GraphQL endpoints and does not support REST APIs.

axios

axios is a popular HTTP client for making requests to REST endpoints. While it is not integrated with Apollo Client, it can be used alongside it to fetch data from REST APIs.

graphql-request

graphql-request is a minimal GraphQL client that can be used to make GraphQL requests. It does not support REST APIs but is a lightweight alternative to Apollo Client for GraphQL-only projects.

README

title: REST Link

⚠️ This library is under active development ⚠️

The Apollo Link Rest library is maintained by Apollo community members and not an Apollo GraphQL maintained library. For information on progress check out the issues or the design. We would love your help with writing docs, testing, anything! We would love for you, yes you, to be a part of the Apollo community!

Purpose

An Apollo Link to easily try out GraphQL without a full server. It can be used to prototype, with third-party services that don't have a GraphQL endpoint or in a transition from REST to GraphQL.

Installation

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.

Usage

Basics

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/',
});

// Configure the ApolloClient with the default cache and RestLink
const client = new ApolloClient({
  link: restLink,
  cache: new InMemoryCache(),
});

// A simple query to retrieve data about the first person
const query = gql`
  query luke {
    person @rest(type: "Person", path: "people/1/") {
      name
    }
  }
`;

// Invoke the query and log the person's name
client.query({ query }).then(response => {
  console.log(response.data.person.name);
});

Apollo Client & React Apollo

For an example of using REST Link with Apollo Client and React Apollo view this CodeSandbox:

TypeScript

For an example of using REST Link with Apollo Client, React Apollo and TypeScript view this CodeSandbox:

Options

REST Link takes an object with some options on it to customize the behavior of the link. The options you can pass are outlined below:

• uri: the URI key is a string endpoint (optional when endpoints provides a default)
• endpoints: root endpoint (uri) to apply paths to or a map of endpoints
• customFetch: a custom fetch to handle REST calls
• headers: an object representing values to be sent as headers on the request
• credentials: a string representing the credentials policy you want for the fetch call
• fieldNameNormalizer: function that takes the response field name and converts it into a GraphQL compliant name

Context

REST Link uses the headers field on the context to allow passing headers to the HTTP request. It also supports the credentials field for defining credentials policy.

• headers: an object representing values to be sent as headers on the request
• credentials: a string representing the credentials policy you want for the fetch call

Documentation

For a complete apollo-link-rest reference visit the documentation website at: https://www.apollographql.com/docs/link/links/rest.html

Contributing

This project uses TypeScript to bring static types to JavaScript and uses Jest for testing. To get started, clone the repo and run the following commands:

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 run the library locally in another project, you can do the following:

npm link

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

Related Libraries

• JSON API Link provides tooling for using GraphQL with JSON API compliant APIs.
• apollo-type-patcher declarative type definitions for your REST API with zero dependencies.

Changelog

v0.9.0

• Feature: Pass context to typePatcher to make it possible to extract args from the URL for use when patching #260 #261
• Feature: Allow per-request field-name normalization for symmetry with de-normalization #253
• Improvement: Use globalThis instead of global #293
• Fix: fieldNameNormalizer mangling ArrayBuffer/Blob types #247
• Drop dependency on graphql-anywhere! #301