response.data or response.result? Why Inconsistent APIs Are Killing Your Frontend Team
A lesson I learned the hard way: Predictability is the best feature of an API.
When I started my career as a Junior Developer working on a legacy project, I had a very simple mindset regarding APIs: “As long as the endpoint returns the correct data, my job is done.”
I didn’t care about the structure. I didn’t care about standardizing keys. If I felt like naming the return property result, I did. If I felt like using data the next day, I did that too.
It seemed harmless at the time. But as the team grew and I started working on features that involved integrating multiple services, I realized I had created a monster.
Here is why inconsistent API responses are a silent killer of productivity, and how we fixed it.
The “Wild West” of Legacy Code
The problem became obvious during a major feature integration. I was working with a Frontend Developer who looked completely frustrated.
“Hey,” he asked, *“For the user profile, is the data inside**response.data,*response.result, or just returned directly at the root?“
I paused. I honestly didn’t know. I had to open the code to check.
We looked at our codebase and found a chaotic mix of styles:
- The Wrapper Wars: Some endpoints returned { data: … }, others { result: … }, and some had no wrapper at all.
- The Casing Clash: Developers coming from Python backgrounds used user_id (snake_case), while JavaScript-focused devs used userId (camelCase).
- The Error Roulette: Some errors returned a 400 status code with a JSON message; others returned a 200 OK but with a { status: “error” } string inside.
The Cost of Inconsistency
This “Wild West” approach didn’t just look ugly; it had real costs:
- Bloated Frontend Code: The frontend team couldn’t create a reusable HTTP handler. They had to write custom parsing logic for every single endpoint.
- Maintenance Nightmares: When we tried to refactor, we broke things constantly because we couldn’t predict the data structure.
- Mental Fatigue: Every time we wrote an API, we wasted time deciding on a structure instead of following a standard.
I realized that in a team environment, your personal coding style matters less than the team’s consistency.
The Solution: The “Minimalist” Standard
When we finally decided to refactor the legacy code, the first thing we discussed was the API Contract.
We didn’t just want consistency; we wanted efficiency. We realized that sending redundant data (like “success”: true or long text messages) in every response was a waste of bandwidth.
So, we established a strict rule: Let the HTTP Headers handle the status, and let the Body handle the context.
Here is the contract we agreed upon:
The Success Response
If the API call is successful, we return an HTTP 2xx status code. For the body, we wrap the content strictly in a data key. We do not send a message string (e.g., “Data loaded successfully”) because it consumes unnecessary bandwidth. If the data arrives, the UI knows what to do.
- Format:
// HTTP Status: 200 OK
{
"data": {
"id": 101,
"fullName": "John Doe",
"email": "john@example.com"
}
}
The Error Response
If the API call fails, we return an HTTP 4xx or 5xx status code. For the body, we only return an error code. We do not send human-readable error messages from the backend. Why? Two reasons:
- Bandwidth: Sending “INVALID_CREDENTIALS” is lighter than sending “The username or password you entered is incorrect.”
- Localization: The Frontend should be responsible for translating the error. By sending a code, the Frontend can easily map INVALID_CREDENTIALS to “Wrong Password” (English) or “Password Salah” (Indonesian) without touching the Backend.
// HTTP Status: 401 Unauthorized
{
"code": "INVALID_CREDENTIALS"
}
The Casing Rule
We agreed to enforce camelCase strictly for all JSON properties, regardless of whether the backend code was written in Python or Node.js.
The Impact: Development Velocity
The impact of this standardization was immediate.
For the Backend Team: We stopped wasting time debating variable names. We adhered to the template, and our code reviews focused on logic rather than semantics.
For the Frontend Team: This was the biggest win. Because the structure was predictable and minimalist, they could write a Global Interceptor (using Axios or Fetch) to handle all responses centrally.
// Example of a Global Interceptor
axios.interceptors.response.use(
(response) => {
// Success: We KNOW the content is always in response.data.data
return response.data.data;
},
(error) => {
// Error: We get the CODE and translate it on the client side
const errorCode = error.response.data.code;
// Mapping the code to a user-friendly language
const userMessage = getTranslation(errorCode);
Notification.error(userMessage);
return Promise.reject(error);
}
);
Final Thoughts
As your team grows, consistency becomes more important than perfection.
It doesn’t matter if you choose snake_case or camelCase. What matters is that everyone on the team follows the same rule.
Refactoring our API responses didn’t just clean up our code; it improved our communication. We stopped guessing keys and started building features.
If you are a Junior Dev or working on a growing team, do yourself a favor: define your response rules early. Your future self (and your frontend team) will thank you.