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
fetchcall inside a component is the beginning of a maintenance problem, not a solution. - A clean data layer separates concerns: one
apiClienthandles 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.
Table of Contents
- 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.
Top comments (52)
@gavincettolo , your article hit a nerve immediately. Especially the part where every project starts with a tiny api.js and six months later nobody wants to touch it anymore.
Have you actually seen that pattern everywhere, or was this inspired by one particularly painful project?
Not everywhere, but I have seen it in many projects.
Different companies, different stacks, same evolution.
It always begins innocently:
Then deadlines arrive.
People duplicate logic.
Auth headers get copy-pasted.
Error handling becomes inconsistent.
Eventually the frontend turns into a distributed network layer nobody understands anymore.
The scary part is that teams normalize it because the app still “works.”
Until scaling starts hurting 😅
That’s exactly what I liked in the article — you framed messy API calls as an architectural debt problem, not just a code style issue.
One thing I’m curious about:
Why did you choose a custom apiClient abstraction instead of recommending Axios directly?
A lot of teams would default to Axios interceptors immediately.
Because I wanted developers to understand the responsibilities first.
Libraries come later.
If you understand:
But if your architecture depends entirely on a library abstraction from day one, developers often never learn why the abstraction exists.
Also, modern fetch is actually pretty capable now.
PS This is another reason: vectra.ai/blog/breaking-down-the-a...
Adding too many ibraries can always be a problem
The AbortController timeout pattern was a nice touch.
Most tutorials completely ignore hanging requests.
Was that included because of real production incidents?
Absolutely, people underestimate how damaging stalled requests are for UX.
Users don’t think:
They think:
Timeouts are one of those invisible quality features.
Nobody notices when they work.
Everybody notices when they don’t.
I also liked your layering breakdown:
lib/
services/
hooks/
It’s simple but scalable.
Do you think frontend developers overcomplicate architecture discussions nowadays?
Sometimes, yes. There’s a tendency to chase complexity because complexity looks senior, but good architecture usually feels boring.
The best systems are predictable.
That clarity is what scales teams.
Not clever abstractions.
That line should honestly be framed in every engineering office.
Another thing:
You recommended TanStack Query instead of manually managing server state.
Do you think useEffect misuse is still one of React’s biggest problems?
100%.
And not because developers are bad.
React unintentionally taught an entire generation that:
So now we have:
Libraries like TanStack Query solve problems teams don’t even realize they have yet.
One part that stood out to me was your comment:
“Each layer does one thing, and only one thing.”
That feels almost like backend architecture philosophy applied to frontend engineering.
Do you think frontend and backend architecture are converging now?
Definitely, Frontend applications today are basically distributed systems with UI attached.
Authentication flows.
Caching.
Concurrency.
Optimistic updates.
Streaming.
Retries.
State synchronization.
Modern frontend engineering is no longer “just UI”, that’s why architectural discipline matters now more than ever.
If you joined a startup tomorrow and found API calls directly inside React components everywhere…
What would be the first thing you’d refactor?
Not everything at once.
That’s how teams create rewrite disasters.
I’d start with:
a shared apiClient,
centralized error handling,
moving auth logic out of components.
Those three changes alone remove a massive amount of chaos.
Then I’d gradually introduce service modules.
Incremental architecture wins long term.
That incremental approach came through strongly in the article.
You never framed it as:
More like:
That’s rare in developer content nowadays.
Because shaming developers is useless.
Most messy codebases are not created by incompetence.
They’re created by:
Good architecture should reduce stress, not increase guilt.
This is a solid guide. The way you broke down the transition from inline fetch spaghetti to a structured, typed data client with AbortController timeouts and automatic token refreshes is spot on. Many tutorials gloss over error handling and token lifecycle management, so seeing those explicitly decoupled from UI logic is highly valuable. 👍
Thanks a lot @syedahmershah! Really appreciate the thoughtful feedback 🙌
I’m glad the separation of concerns came through clearly, especially around error handling and token lifecycle management. Those are usually the first things that become painful once an app grows, but they often get skipped in simpler examples.
My goal with the article was exactly to show how a small amount of structure in the data layer can make the rest of the app much easier to reason about and maintain over time.
And yes, AbortController + centralized refresh handling have been huge quality-of-life improvements for me in real projects 😄
Thanks again for taking the time to read and comment!
Centralized refresh handling and AbortController are exactly what separate production code from tutorial code. Thanks for putting together such a clean, practical guide! 👍
That’s a great way to put it “production code vs tutorial code” is exactly the gap I wanted to address with the article 🙂
A lot of examples stop at “it works”, but in real applications the hard part is usually everything around the request itself: cancellation, retries, auth state, consistency, error propagation, and keeping UI components free from networking concerns.
Glad you found the guide practical and grounded in real-world needs. Thanks again for the thoughtful feedback 🙌
That's a great article!! 💯💯💯
It makes things easy to read and understand with this way of structuring, also changes to code are predictable and non threatening 😂
Thank you @paras594!
If you have any thoughts or suggestions, I'm all ears.
Sure, will do!
Some of you may have noticed that localStorage is vulnerable to XSS attacks and that tokens should be stored in httpOnly cookies.
This is absolutely correct!
localStorage is used here for simplicity; in production, httpOnly cookies are the most secure choice.
Worth a dedicated article on auth security.
What common problems did you see when you started refactoring messy fetches in components?
I found duplicated logic, inconsistent error handling, tangled concerns (UI vs data fetching), and tests that were hard to write. Components became large and brittle because they managed both rendering and data access.
Why build a separate data layer instead of keeping fetch logic in hooks or components?
A data layer centralizes API contracts and caching, enforces a single source of truth, and makes components simpler and easier to test. Hooks still have a role for integration, but the data layer handles request construction, normalization, and error mapping.
Can you summarize the pattern you recommend?
Split responsibilities: an API client for low-level HTTP, a repository/service layer for business-specific requests and response shaping, and lightweight hooks or connectors for component use. Add a consistent error model and optional caching at the data layer.
How do you handle side effects like retries, optimistic updates, or real-time updates?
Keep retries and cache policies in the data layer or the caching layer; use optimistic updates in higher-level services that coordinate state updates and server calls. For real-time, integrate websockets or subscriptions into the same data layer so subscribers receive normalized updates.
What trade-offs should teams expect when adopting this approach?
Initial complexity and boilerplate increase, and you may over-architect for small apps. The payoff is testability, consistency, and easier scaling for medium-to-large apps.
How do you test the data layer and the components separately?
A lot of questions ahah Thanks @elenchen :)
Unit-test API client and services with mocked fetch/XHR, use contract tests for request/response shapes, and test hooks/components with mocked repositories so UI tests don't depend on network calls.
Yes, I am really curious!
Any advice for migrating an existing messy codebase incrementally?
I can suggest you to start with one domain or endpoint: extract the client, then a service, then replace in components. Add tests as you go and keep behavior identical during the transition to reduce risk.
What libraries or tools pair well with this architecture?
Minimal dependencies are fine, but tools like Axios or ky for HTTP, zod or io-ts for runtime validation, React Query or SWR for caching if you want advanced features, and msw for testing.
Thank you @gavincettolo for your patience!
You are welcome @elenchen
This is a clean progression — building up one responsibility at a time makes it easy to follow, and the fetch not throwing on 4xx/5xx point is one of those things that bites everyone exactly once. The typed ApiError getters beat the string-matching mess most codebases end up with.
One addition: for production auth, refresh token in an httpOnly cookie + access token in memory survives XSS better than localStorage and costs you nothing but a re-auth on hard refresh. (Saw you already flagged the cookie point in the comments — good call.)
Honestly my setup is close to this, and you nailed the real lesson in the final thoughts: doing the steps in order is what makes it work. Great series. 🦄
Thanks a lot @neletomartin, this is such a thoughtful breakdown 🙌
You’re absolutely right about
fetchnot throwing on 4xx/5xx responses. That’s one of those JavaScript “gotchas” everyone eventually learns the hard way 😄And I completely agree on the auth strategy. Using an httpOnly refresh token cookie with the access token kept in memory is definitely the safer production-grade approach, especially from an XSS perspective. I wanted the article to stay focused on the data layer architecture itself, but I’m glad you highlighted that nuance here.
Also happy the
ApiErrorapproach resonated with you, I’ve seen too many codebases drift into brittle string matching over time, so having typed guards/helpers has saved me a lot of debugging pain.Really appreciate the kind words about the progression too. That was actually the main challenge while writing this: making each abstraction feel justified instead of “enterprise for the sake of enterprise” 😄
Thanks again for reading and sharing your experience!
This is an excellent guide on structuring API calls. Moving from messy fetch to a clean data layer is a game-changer for maintainability. Thanks for sharing these insights!
Thanks @aasteriskz
Solid! (little "play of words")
Haha, I’ll take the pun and the compliment 😄
Glad you enjoyed it, hopefully the architecture stays “solid” even after a few production deadlines hit 🚀
Yeah this is a pretty cool structure/design ...
I did an API interface in React (with Typescript) some time ago, and I did implement a few aspects/pieces of what you described, but certainly not all of it, only a small part - and I didn't really type my API properly, all the "fields" went in/out as strings (I did use structs/types but used "string" for all the props/attributes) ...
Had been planning to redesign/refactor that for a long time - I'm probably gonna use your design when I do!
Keep me updated :)
Great article!
(to disclose) Co-founder of Faultline Security here.
Worth noting: a centralized data layer isn't just cleaner, it's also where you can enforce security concerns in one place.
Thanks a lot @albernaz_! And absolutely, that’s a really important point.
A centralized data layer becomes the perfect place to enforce cross-cutting concerns consistently: auth handling, request validation, retry policies, rate limiting, logging, telemetry, even security-related protections like CSRF handling or token rotation logic.
That’s actually one of the biggest long-term advantages over scattered inline
fetchcalls: you gain a single control surface for behavior that should stay consistent across the entire app.Really appreciate you adding that perspective, especially coming from the security side of things 🙌
Some comments may only be visible to logged-in visitors. Sign in to view all comments.