API Calls Done Right: From Messy Fetch to Clean Data Layer

I've seen this file in almost every frontend project I've ever touched.

It's usually called api.js or utils.js or sometimes just helpers.ts.

It starts small. One function. Two functions.

Then, six months later, it's 800 lines long, nobody fully understands it, and everyone is afraid to change it.

It looks something like this:

// Somewhere in a React component, at 3pm on a sprint deadline
const res = await fetch(`/api/users/${id}`, {
  headers: { Authorization: `Bearer ${localStorage.getItem('token')}` }
})
const data = await res.json()
setUser(data)

No error handling. No type safety. Auth logic scattered across components. The token read inline from localStorage every single time.

It works, until it doesn't.

This article is about building something better. We'll start from that messy fetch call and work our way up to a clean, typed, maintainable data layer, step by step.

TL;DR

A raw fetch call inside a component is the beginning of a maintenance problem, not a solution.
A clean data layer separates concerns: one apiClient handles transport and auth, individual service modules handle domain logic.
TypeScript + structured error handling + automatic token refresh gives you a production-grade setup that scales without becoming a second job to maintain.

What We're Building (and Why)
Step 1: The apiClient - One Place for Transport Logic
Step 2: Typed Responses and Structured Error Handling
Step 3: Service Modules — Organizing by Domain
Step 4: Authentication — Bearer Tokens Done Right
Step 5: Automatic Token Refresh
Step 6: Connecting the Data Layer to React with TanStack Query
The Final Folder Structure
Final Thoughts

What We're Building (and Why)

Before writing any code, let's define what "clean data layer" actually means.

It's not a framework. It's not a library. It's a set of responsibilities, each living in the right place:

Responsibility	Where it lives
HTTP transport (headers, base URL, timeouts)	`apiClient`
Auth token management	`apiClient` + `tokenService`
Domain-specific calls (fetch user, update product)	Service modules
Server state, caching, loading/error UI state	TanStack Query
Business logic and rendering	React components

A React component that directly calls fetch is doing two jobs at once: fetching data and rendering UI. That coupling is the root cause of most of the problems we're trying to solve.

The goal is simple: each layer does one thing, and only one thing.

Step 1: The apiClient - One Place for Transport Logic

The first thing we need is a single, shared HTTP client. Every API call in the application goes through it. No exceptions.

This gives us one place to configure:

the base URL
default headers
timeout behavior
future interceptors

// src/lib/apiClient.ts

const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? 'https://api.example.com'
const DEFAULT_TIMEOUT_MS = 10_000

interface RequestOptions extends RequestInit {
  timeout?: number
}

async function request<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), timeout)

  const url = `${BASE_URL}${endpoint}`

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
      headers: {
        'Content-Type': 'application/json',
        ...fetchOptions.headers,
      },
    })

    if (!response.ok) {
      throw new ApiError(response.status, await response.text())
    }

    // Handle 204 No Content
    if (response.status === 204) {
      return undefined as T
    }

    return response.json() as Promise<T>
  } finally {
    clearTimeout(timeoutId)
  }
}

export const apiClient = {
  get: <T>(endpoint: string, options?: RequestOptions) =>
    request<T>(endpoint, { ...options, method: 'GET' }),

  post: <T>(endpoint: string, body: unknown, options?: RequestOptions) =>
    request<T>(endpoint, {
      ...options,
      method: 'POST',
      body: JSON.stringify(body),
    }),

  put: <T>(endpoint: string, body: unknown, options?: RequestOptions) =>
    request<T>(endpoint, {
      ...options,
      method: 'PUT',
      body: JSON.stringify(body),
    }),

  patch: <T>(endpoint: string, body: unknown, options?: RequestOptions) =>
    request<T>(endpoint, {
      ...options,
      method: 'PATCH',
      body: JSON.stringify(body),
    }),

  delete: <T>(endpoint: string, options?: RequestOptions) =>
    request<T>(endpoint, { ...options, method: 'DELETE' }),
}

A few things worth noting here:

The AbortController + timeout pattern ensures that hanging requests don't freeze the UI indefinitely. After DEFAULT_TIMEOUT_MS, the request is automatically cancelled.

The if (!response.ok) check is something the native fetch API does not do for you. A fetch call to an endpoint that returns 404 or 500 will not throw, it resolves successfully, with response.ok set to false. If you don't check this, you'll silently pass error responses to your state as if they were valid data.

The 204 No Content guard prevents response.json() from throwing on empty responses, which is a surprisingly common gotcha with DELETE endpoints.

Step 2: Typed Responses and Structured Error Handling

The apiClient above throws an ApiError. Let's define it.

// src/lib/errors.ts

export class ApiError extends Error {
  constructor(
    public readonly status: number,
    public readonly body: string,
    message?: string
  ) {
    super(message ?? `API error: ${status}`)
    this.name = 'ApiError'
  }

  get isUnauthorized(): boolean {
    return this.status === 401
  }

  get isForbidden(): boolean {
    return this.status === 403
  }

  get isNotFound(): boolean {
    return this.status === 404
  }

  get isServerError(): boolean {
    return this.status >= 500
  }
}

export class NetworkError extends Error {
  constructor(message = 'Network request failed') {
    super(message)
    this.name = 'NetworkError'
  }
}

Having a typed error class instead of a generic Error is what makes downstream error handling clean. In your components or TanStack Query callbacks, you can now write:

if (error instanceof ApiError && error.isUnauthorized) {
  // redirect to login
}

Instead of:

// ❌ What most codebases end up with
if (error.message.includes('401') || error.message.includes('Unauthorized')) {
  // fragile, brittle, and a maintenance nightmare
}

Step 3: Service Modules — Organizing by Domain

Now that we have a shared client and typed errors, we can build service modules on top of it.

A service module groups all API calls related to a single domain. One file per domain. No mixing.

// src/services/userService.ts

import { apiClient } from '@/lib/apiClient'

export interface User {
  id: string
  email: string
  firstName: string
  lastName: string
  role: 'admin' | 'user'
  createdAt: string
}

export interface UpdateUserPayload {
  firstName?: string
  lastName?: string
  email?: string
}

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

export const userService = {
  getById: (id: string) =>
    apiClient.get<User>(`/users/${id}`),

  getAll: (page = 1, pageSize = 20) =>
    apiClient.get<PaginatedResponse<User>>(
      `/users?page=${page}&pageSize=${pageSize}`
    ),

  update: (id: string, payload: UpdateUserPayload) =>
    apiClient.patch<User>(`/users/${id}`, payload),

  delete: (id: string) =>
    apiClient.delete<void>(`/users/${id}`),
}

// src/services/productService.ts

import { apiClient } from '@/lib/apiClient'

export interface Product {
  id: string
  name: string
  price: number
  stock: number
  categoryId: string
}

export interface CreateProductPayload {
  name: string
  price: number
  stock: number
  categoryId: string
}

export const productService = {
  getById: (id: string) =>
    apiClient.get<Product>(`/products/${id}`),

  create: (payload: CreateProductPayload) =>
    apiClient.post<Product>('/products', payload),

  updateStock: (id: string, stock: number) =>
    apiClient.patch<Product>(`/products/${id}`, { stock }),
}

This pattern scales cleanly. When a new developer joins and needs to find where user-related API calls live, the answer is always the same: src/services/userService.ts.

No archaeology. No searching for fetch('/api/users' across twelve components.

Step 4: Authentication - Bearer Tokens Done Right

Right now, the apiClient doesn't know anything about authentication. Let's fix that.

The wrong way to handle this is what we saw at the start: reading localStorage.getItem('token') inline inside every component. The token management logic is scattered, untestable, and fragile.

The right way is a dedicated tokenService that the apiClient calls when it needs to attach credentials.

// src/lib/tokenService.ts

const ACCESS_TOKEN_KEY = 'access_token'
const REFRESH_TOKEN_KEY = 'refresh_token'

export const tokenService = {
  getAccessToken: (): string | null =>
    localStorage.getItem(ACCESS_TOKEN_KEY),

  getRefreshToken: (): string | null =>
    localStorage.getItem(REFRESH_TOKEN_KEY),

  setTokens: (accessToken: string, refreshToken: string): void => {
    localStorage.setItem(ACCESS_TOKEN_KEY, accessToken)
    localStorage.setItem(REFRESH_TOKEN_KEY, refreshToken)
  },

  clearTokens: (): void => {
    localStorage.removeItem(ACCESS_TOKEN_KEY)
    localStorage.removeItem(REFRESH_TOKEN_KEY)
  },

  hasValidToken: (): boolean =>
    tokenService.getAccessToken() !== null,
}

Now we update apiClient to attach the token automatically:

// src/lib/apiClient.ts - updated request function

async function request<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), timeout)

  // Attach auth header automatically if token exists
  const accessToken = tokenService.getAccessToken()
  const authHeader = accessToken
    ? { Authorization: `Bearer ${accessToken}` }
    : {}

  const url = `${BASE_URL}${endpoint}`

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
      headers: {
        'Content-Type': 'application/json',
        ...authHeader,           // injected here - not in components
        ...fetchOptions.headers, // allow per-request overrides
      },
    })

    if (!response.ok) {
      throw new ApiError(response.status, await response.text())
    }

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

    return response.json() as Promise<T>
  } finally {
    clearTimeout(timeoutId)
  }
}

Now every call made through apiClient automatically includes the auth header. Components don't know that auth exists. They just call userService.getById(id) and get back a typed User.

Step 5: Automatic Token Refresh

The Bearer token setup works - but in production, access tokens expire. Usually after 15–60 minutes.

Without automatic refresh, the user gets a 401 error and is silently logged out, even though their session is still valid. That's a frustrating experience and it's entirely avoidable.

The pattern is:

Request fails with 401.
Intercept the error before it reaches the component.
Use the refresh token to get a new access token.
Retry the original request with the new token.
If the refresh also fails, clear tokens and redirect to login.

// src/lib/apiClient.ts - with refresh logic

let isRefreshing = false
let pendingRequests: Array<(token: string) => void> = []

async function refreshAccessToken(): Promise<string> {
  const refreshToken = tokenService.getRefreshToken()

  if (!refreshToken) {
    throw new Error('No refresh token available')
  }

  // Note: this call bypasses the main request() to avoid infinite loops
  const response = await fetch(`${BASE_URL}/auth/refresh`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken }),
  })

  if (!response.ok) {
    throw new ApiError(response.status, await response.text())
  }

  const { accessToken, refreshToken: newRefreshToken } = await response.json()
  tokenService.setTokens(accessToken, newRefreshToken)

  return accessToken
}

async function request<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), timeout)

  const accessToken = tokenService.getAccessToken()
  const authHeader = accessToken
    ? { Authorization: `Bearer ${accessToken}` }
    : {}

  const url = `${BASE_URL}${endpoint}`

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
      headers: {
        'Content-Type': 'application/json',
        ...authHeader,
        ...fetchOptions.headers,
      },
    })

    // Token expired - attempt refresh
    if (response.status === 401 && tokenService.getRefreshToken()) {
      // If a refresh is already in flight, queue this request
      if (isRefreshing) {
        return new Promise<T>((resolve, reject) => {
          pendingRequests.push((newToken: string) => {
            fetchOptions.headers = {
              ...fetchOptions.headers,
              Authorization: `Bearer ${newToken}`,
            }
            request<T>(endpoint, options).then(resolve).catch(reject)
          })
        })
      }

      isRefreshing = true

      try {
        const newToken = await refreshAccessToken()

        // Flush queued requests with the new token
        pendingRequests.forEach(callback => callback(newToken))
        pendingRequests = []

        // Retry the original request
        return request<T>(endpoint, options)
      } catch {
        // Refresh failed - session is truly expired
        tokenService.clearTokens()
        pendingRequests = []
        window.location.href = '/login'
        throw new Error('Session expired')
      } finally {
        isRefreshing = false
      }
    }

    if (!response.ok) {
      throw new ApiError(response.status, await response.text())
    }

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

    return response.json() as Promise<T>
  } finally {
    clearTimeout(timeoutId)
  }
}

The isRefreshing flag and pendingRequests queue are important. Without them, if five requests fire simultaneously and all get a 401, you'd fire five parallel refresh calls - a race condition that corrupts your token storage. With the queue, only one refresh happens, and all pending requests retry with the new token once it's available.

Step 6: Connecting the Data Layer to React with TanStack Query

The data layer we've built is framework-agnostic. It's just TypeScript functions. You can use it anywhere.

But in a React app, you'll want to connect it to your component state in a structured way. That's where TanStack Query comes in - and it pairs with this data layer perfectly.

// src/hooks/useUser.ts

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { userService, UpdateUserPayload } from '@/services/userService'

export function useUser(userId: string) {
  return useQuery({
    queryKey: ['users', userId],
    queryFn: () => userService.getById(userId),
    staleTime: 1000 * 60 * 5, // 5 minutes
  })
}

export function useUsers(page: number, pageSize: number) {
  return useQuery({
    queryKey: ['users', { page, pageSize }],
    queryFn: () => userService.getAll(page, pageSize),
    placeholderData: previousData => previousData, // smooth pagination
  })
}

export function useUpdateUser(userId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (payload: UpdateUserPayload) =>
      userService.update(userId, payload),
    onSuccess: updatedUser => {
      // Update the cached user immediately - no refetch needed
      queryClient.setQueryData(['users', userId], updatedUser)
    },
  })
}

And in the component, it's now completely clean:

// src/components/UserProfile.tsx

import { useUser, useUpdateUser } from '@/hooks/useUser'
import { ApiError } from '@/lib/errors'

interface Props {
  userId: string
}

export function UserProfile({ userId }: Props) {
  const { data: user, isLoading, error } = useUser(userId)
  const { mutate: updateUser, isPending } = useUpdateUser(userId)

  if (isLoading) return <Spinner />

  if (error) {
    if (error instanceof ApiError && error.isNotFound) {
      return <p>User not found.</p>
    }
    return <p>Something went wrong. Please try again.</p>
  }

  if (!user) return null

  const fullName = `${user.firstName} ${user.lastName}`

  return (
    <div>
      <h1>{fullName}</h1>
      <p>{user.email}</p>
      <button
        onClick={() => updateUser({ firstName: 'Updated' })}
        disabled={isPending}
      >
        Update
      </button>
    </div>
  )
}

The component knows nothing about:

how HTTP requests are made
where tokens come from
how errors are structured at the network level
what happens on a 401

It just asks for data and renders it. That's the goal.

If you want to go deeper on TanStack Query and why the queryKey matters, I covered it in detail in Stop Using useEffect Like This.

TanStack Query

Powerful asynchronous state management, server-state utilities and data fetching. Fetch, cache, update, and wrangle all forms of async data in your TS/JS, React, Vue, Solid, Svelte, Angular & Lit applications all without touching any "global state"

tanstack.com

The Final Folder Structure

After all six steps, here's what the data layer looks like on disk:

src/
├── lib/
│   ├── apiClient.ts       # HTTP transport, auth headers, token refresh
│   ├── tokenService.ts    # Token read/write/clear
│   └── errors.ts          # ApiError, NetworkError
│
├── services/
│   ├── userService.ts     # All user-related API calls + types
│   ├── productService.ts  # All product-related API calls + types
│   └── authService.ts     # Login, logout, register
│
└── hooks/
    ├── useUser.ts         # TanStack Query hooks for user data
    └── useProducts.ts     # TanStack Query hooks for product data

Three layers, three responsibilities:

lib/ - infrastructure. Doesn't know about your business domain.
services/ - domain. Knows about users, products, orders. Doesn't know about React.
hooks/ - React integration. Bridges the service layer with component state.

A component that needs user data goes through hooks/. A non-React module (a utility, a test) can call services/ directly. Nothing ever touches lib/ directly except services/.

Final Thoughts

We started with a fetch call inside a component, reading a token from localStorage inline.

We ended with a layered system where:

HTTP logic lives in one place
Auth is automatic and transparent
Every API call is typed
Token refresh happens without the user noticing
React components have no idea how any of this works

None of these steps are complicated individually. The value comes from doing all of them, and doing them in order.

You don't have to build this in one day. Start with the apiClient and the service modules. Add auth when you need it. Add token refresh when access tokens start expiring. Add TanStack Query when you need caching.

Each step is independently useful. The full stack is production-grade.

This article is part of the **Modern Frontend* series.*
If you missed the first article: Stop Using useEffect Like This - 5 Patterns That Break Your React App.

What does your current API layer look like?

Are you still writing fetch calls directly in components, or have you already built something like this? Drop your setup in the comments - I'm curious how different teams solve this problem.

If this was useful, a ❤️ or a 🦄 means a lot.
And if you want the next article in the series when it drops, hit follow.

推荐订阅源

DEV Community