Skip to content
Sameer Sabir
React

REST and GraphQL API Integration Patterns in React and Next.js

Master API integration in React and Next.js with REST, GraphQL, Apollo Client, error handling, caching, and real-world optimization patterns.

Sameer SabirUpdated 10 min read
  • REST API
  • GraphQL
  • Apollo Client
  • React
  • Next.js
  • TypeScript

API integration is where frontend meets reality. The elegance of your components doesn't matter if data flows are fragile, slow, or hard to maintain. Having built applications with both REST APIs and GraphQL — including a B2B commerce platform with Apollo Client that achieved 40% faster data loading — I've developed patterns that keep API layers clean, type-safe, and performant. This guide covers both paradigms and when to use each.

REST API Patterns

Type-Safe API Client

Create a centralized client with proper error handling and interceptors:

// lib/api-client.ts
interface ApiConfig {
  baseUrl: string;
  getToken?: () => string | null;
}

class ApiClient {
  private baseUrl: string;
  private getToken?: () => string | null;

  constructor(config: ApiConfig) {
    this.baseUrl = config.baseUrl;
    this.getToken = config.getToken;
  }

  private async request<T>(
    endpoint: string,
    options: RequestInit = {}
  ): Promise<T> {
    const headers: HeadersInit = {
      'Content-Type': 'application/json',
      ...options.headers,
    };

    const token = this.getToken?.();
    if (token) {
      (headers as Record<string, string>)['Authorization'] = `Bearer ${token}`;
    }

    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers,
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new ApiError(response.status, error.message || `API error: ${response.status}`);
    }

    if (response.status === 204) return undefined as T;
    return response.json();
  }

  get<T>(endpoint: string, params?: Record<string, string>) {
    const url = params
      ? `${endpoint}?${new URLSearchParams(params)}`
      : endpoint;
    return this.request<T>(url);
  }

  post<T>(endpoint: string, body: unknown) {
    return this.request<T>(endpoint, {
      method: 'POST',
      body: JSON.stringify(body),
    });
  }

  patch<T>(endpoint: string, body: unknown) {
    return this.request<T>(endpoint, {
      method: 'PATCH',
      body: JSON.stringify(body),
    });
  }

  delete<T>(endpoint: string) {
    return this.request<T>(endpoint, { method: 'DELETE' });
  }
}

export const api = new ApiClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL || '/api',
  getToken: () => {
    if (typeof window === 'undefined') return null;
    return localStorage.getItem('auth_token');
  },
});

Resource-Based Service Layer

// services/projectService.ts
import { api } from '@/lib/api-client';

export interface Project {
  id: string;
  title: string;
  description: string;
  status: 'draft' | 'active' | 'completed';
  technologies: string[];
  createdAt: string;
}

interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  pageSize: number;
}

export const projectService = {
  list: (params?: { page?: number; status?: string }) =>
    api.get<PaginatedResponse<Project>>('/projects', params as Record<string, string>),

  getById: (id: string) =>
    api.get<Project>(`/projects/${id}`),

  create: (data: Omit<Project, 'id' | 'createdAt'>) =>
    api.post<Project>('/projects', data),

  update: (id: string, data: Partial<Project>) =>
    api.patch<Project>(`/projects/${id}`, data),

  delete: (id: string) =>
    api.delete(`/projects/${id}`),
};

Next.js Server Actions for Form Mutations

// app/projects/actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createProject(formData: FormData) {
  const title = formData.get('title') as string;
  const description = formData.get('description') as string;

  if (!title?.trim()) {
    return { error: 'Title is required' };
  }

  try {
    const response = await fetch(`${process.env.API_URL}/projects`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ title, description }),
    });

    if (!response.ok) {
      const error = await response.json();
      return { error: error.message || 'Failed to create project' };
    }

    revalidatePath('/projects');
    return { success: true };
  } catch {
    return { error: 'Network error. Please try again.' };
  }
}

GraphQL with Apollo Client

Apollo Client Setup for Next.js

// lib/apollo-client.ts
import { ApolloClient, InMemoryCache, HttpLink, from } from '@apollo/client';
import { onError } from '@apollo/client/link/error';
import { RetryLink } from '@apollo/client/link/retry';

const httpLink = new HttpLink({
  uri: process.env.NEXT_PUBLIC_GRAPHQL_URL,
});

const errorLink = onError(({ graphQLErrors, networkError }) => {
  if (graphQLErrors) {
    graphQLErrors.forEach(({ message, locations, path }) =>
      console.error(`[GraphQL error]: ${message}`, { locations, path })
    );
  }
  if (networkError) {
    console.error(`[Network error]: ${networkError}`);
  }
});

const retryLink = new RetryLink({
  delay: { initial: 300, max: 3000, jitter: true },
  attempts: { max: 3, retryIf: (error) => !!error },
});

export const apolloClient = new ApolloClient({
  link: from([retryLink, errorLink, httpLink]),
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          projects: {
            keyArgs: ['status'],
            merge(existing = [], incoming) {
              return [...existing, ...incoming];
            },
          },
        },
      },
    },
  }),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network',
    },
  },
});

Type-Safe Queries with Code Generation

# graphql/queries/projects.graphql
query GetProjects($status: ProjectStatus, $page: Int, $limit: Int) {
  projects(status: $status, page: $page, limit: $limit) {
    data {
      id
      title
      description
      status
      technologies
      image
      createdAt
    }
    total
    hasNextPage
  }
}

query GetProject($id: ID!) {
  project(id: $id) {
    id
    title
    description
    status
    technologies
    image
    links {
      live
      github
    }
    createdAt
    updatedAt
  }
}

mutation CreateProject($input: CreateProjectInput!) {
  createProject(input: $input) {
    id
    title
    status
  }
}

Using Generated Hooks

// components/ProjectList.tsx
'use client';

import { useGetProjectsQuery } from '@/generated/graphql';

function ProjectList({ status }: { status?: string }) {
  const { data, loading, error, fetchMore } = useGetProjectsQuery({
    variables: { status, page: 1, limit: 12 },
    notifyOnNetworkStatusChange: true,
  });

  if (error) return <ErrorMessage error={error} />;

  const projects = data?.projects.data ?? [];
  const hasNextPage = data?.projects.hasNextPage;

  return (
    <div>
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {loading && !projects.length
          ? Array.from({ length: 6 }).map((_, i) => <ProjectSkeleton key={i} />)
          : projects.map((project) => (
              <ProjectCard key={project.id} project={project} />
            ))}
      </div>

      {hasNextPage && (
        <button
          onClick={() =>
            fetchMore({
              variables: { page: Math.ceil(projects.length / 12) + 1 },
            })
          }
          disabled={loading}
          className="mt-8 px-6 py-3 bg-cyan-600 rounded-lg hover:bg-cyan-700"
        >
          {loading ? 'Loading...' : 'Load More'}
        </button>
      )}
    </div>
  );
}

REST vs GraphQL: When to Use Which

CriteriaRESTGraphQL
Data shape varies per viewOver/under-fetchingRequest exact fields
Simple CRUDNatural fitOverkill
Real-time updatesWebSockets/SSESubscriptions built-in
File uploadsStraightforwardRequires multipart spec
CachingHTTP cache headersNormalized client cache
Team sizeAnyBenefits larger teams
Mobile + WebMultiple endpointsOne endpoint, different queries

My rule of thumb: Use REST for simple APIs and server-to-server communication. Use GraphQL when multiple clients need different data shapes from the same backend — exactly the case in B2B commerce platforms where dashboards, mobile apps, and public pages all consume the same data differently.

Error Handling Patterns

Unified Error Boundary

'use client';

import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error, resetErrorBoundary }: {
  error: Error;
  resetErrorBoundary: () => void;
}) {
  return (
    <div className="p-6 bg-red-900/20 border border-red-800 rounded-xl text-center">
      <h3 className="text-lg font-semibold text-red-400">Something went wrong</h3>
      <p className="text-sm text-gray-400 mt-2">{error.message}</p>
      <button
        onClick={resetErrorBoundary}
        className="mt-4 px-4 py-2 bg-red-600 rounded-lg hover:bg-red-700 text-sm"
      >
        Try Again
      </button>
    </div>
  );
}

export function QueryErrorBoundary({ children }: { children: React.ReactNode }) {
  const { reset } = useQueryErrorResetBoundary();

  return (
    <ErrorBoundary FallbackComponent={ErrorFallback} onReset={reset}>
      {children}
    </ErrorBoundary>
  );
}

Key Takeaways

  1. Centralized API client — Single source for auth headers, error handling, and base URL
  2. Service layer per resource — Type-safe functions that abstract HTTP details
  3. GraphQL for complex data needs — Normalized caching and exact field selection
  4. Server Actions for mutations — Automatic revalidation with revalidatePath
  5. Apollo cache policies — Customize merge strategies for pagination
  6. Error boundaries — Graceful degradation instead of white screens

Clean API integration is what separates hobby projects from production applications. Invest in your data layer, and every component built on top of it becomes simpler and more reliable.

Integration work is where most timelines quietly slip. If you want the API layer designed once rather than patched repeatedly, that is REST and GraphQL API integration — tell me what you are connecting.

  1. GraphQL and Apollo Client in React: From Setup to Production PatternsReact · 13 min
  2. Mastering Framer Motion: Production-Grade Animations for React ApplicationsReact · 11 min
  3. React 19 Server Actions: The Complete Guide to Full-Stack React DevelopmentReact · 12 min

Next step

Have a project that needs this kind of work?

I build React and Next.js products end to end, including the performance and AI work these posts cover. Tell me where yours is stuck.