DEV Community: Wongsaphat Nakmuang

Before You Write a Single Line: How to Plan Your API Like a Senior Engineer

Wongsaphat Nakmuang — Mon, 08 Jun 2026 04:19:46 +0000

In my second week at work, I watched a senior engineer spend 3 days refactoring an API that took 1 day to build.

The endpoint worked. The logic was correct. The code was clean.

But halfway through integration, the frontend team came back with a list of questions:

"Why does this return a nested object here but a flat array there?"
"Where's the pagination? We assumed it would be paginated."
"What does error code 14 mean?"

Nobody planned it. Everyone assumed. And three days of refactoring followed.

That week I learned something more valuable than any syntax or framework:

The most expensive code to write is the code you have to rewrite.

Why Most Developers Skip Planning

It's not laziness. Nobody taught us this part.

Tutorials teach us how to build an API. They show us frameworks, authentication patterns, database queries. But they almost never show us what happens in the 30 minutes before the first line of code — the thinking, the questioning, the scoping.

So we do what feels natural: we open VS Code and start.

The result is usually the same. We build fast, hit unexpected problems, patch things, and ship something that technically works but is painful to maintain, extend, or explain to anyone else.

Here's the process I've been learning — 5 steps that happen before a single endpoint is written.

Step 1: Define "What Is This API?" in One Sentence

Before anything else, you need to answer three questions. If you can't answer all three clearly, you're not ready to start.

Who will call this API?

A frontend web app?
A mobile client?
Another backend service?
A third-party developer?

The answer changes everything — response structure, authentication method, error detail level.

What does it do?

Can you explain it in one sentence to someone who isn't a developer?
If your answer is longer than two sentences, the scope is probably too broad.

Why does it need to exist?

Does something similar already exist in the codebase?
Are you solving a real, confirmed need — or building something "that might be useful"?

💡 My rule: If I can't explain this API to my mom in 30 seconds, I don't understand it well enough to build it yet.

Step 2: Draw the Scope Before Writing Endpoints

Get a piece of paper. Or open a blank Markdown file. Or use Miro. The tool doesn't matter.

Draw the resources your API will manage and how they relate to each other.

Example — a simple task management API:

Resources:
- User
- Project  
- Task
- Comment

Relationships:
- User has many Projects
- Project has many Tasks
- Task has many Comments
- Task belongs to one User (assignee)

Then for each resource, define what operations are actually needed right now:

Task:
  ✅ GET    /tasks          → list tasks (with filters)
  ✅ POST   /tasks          → create task
  ✅ GET    /tasks/:id      → get single task
  ✅ PATCH  /tasks/:id      → update task
  ✅ DELETE /tasks/:id      → delete task

  ❌ GET    /tasks/archive  → not needed yet, skip
  ❌ POST   /tasks/bulk     → not needed yet, skip

The most important discipline here is cutting scope ruthlessly.

Every "nice to have" endpoint you add now is technical debt you'll maintain forever. Build what's confirmed needed. Add the rest later when there's actual demand.

💡 The question that saves hours: "Is this needed for the first release, or is it something we think might be useful someday?"

Step 3: Identify the Risks Before You Estimate

This is the step that most junior developers skip — and it's why our estimates are almost always wrong.

Before you write a single line, spend 15 minutes asking: "What don't I know yet?"

Go through this checklist:

Authentication & Authorization

Does this API require authentication? What kind? (JWT, API Key, OAuth?)
Are there different user roles with different permissions?
Which endpoints are public? Which are protected?

Data

Where does the data come from? An existing database? A new one?
What does the current schema look like? Any constraints?
Are there existing APIs that touch the same data?

Scale

How many requests per day is realistic?
Does any endpoint need pagination?
Are there operations that could be slow? (File uploads, external API calls, heavy queries)

Dependencies

Does this API call any external services? (Payment gateway, email, SMS)
What happens if those services are down?

Every risk you find now is a problem you won't have to solve at 11pm the night before the deadline.

💡 Real talk: When I got my first API task, I estimated 2 days. I hadn't asked about authentication, pagination, or the fact that the data came from a legacy system with an unusual schema. It took 5 days. The 30 minutes of risk identification would have saved me 3 days of surprises.

Step 4: Write the Contract Before the Code

A contract is not code. It's a simple document — can be Markdown, a Notion page, a whiteboard photo — that describes what each endpoint will accept and return.

Here's what a contract looks like for one endpoint:

POST /tasks

Description:
  Create a new task and assign it to a project

Request Body:
  {
    "title": string (required, max 200 chars)
    "description": string (optional)
    "projectId": uuid (required)
    "assigneeId": uuid (optional)
    "dueDate": ISO date string (optional)
  }

Success Response (201):
  {
    "status": "success",
    "data": {
      "id": uuid,
      "title": string,
      "status": "todo",
      "createdAt": timestamp
    }
  }

Error Cases:
  400 → missing required fields
  404 → projectId not found
  403 → user doesn't have access to this project

Writing this takes about 10 minutes per endpoint.

The benefit is immediate: your frontend teammate can start building mock responses the same day — without waiting for you to finish the backend. You're no longer a blocker.

And when you sit down to write the actual code, you already know exactly what you're building. No decision fatigue. No ambiguity. Just execution.

💡 Pro tip: Show this contract to your frontend dev before you start coding. If they have questions or "that's not quite what I need" feedback — far better to discover that now than after you've shipped.

Step 5: Consult and Align With Your Team

This is the step most tutorials never mention. And it's the one that separates developers who work well in teams from those who don't.

Before you write the first line of code, take your contract and your scope document and show them to someone.

Questions to ask:

To your senior engineer or tech lead:

"Does this approach make sense? Is there anything I'm missing?"
"Are there patterns in this codebase I should follow?"
"Do you see any risk I haven't thought of?"

To your frontend developer (if there is one):

"Does this response structure work for what you're building?"
"Is there anything you need that isn't here?"

To yourself (seriously — write it down):

"Can I explain this to someone in 2 minutes?"
"If I was sick tomorrow, could someone else pick this up?"

Asking "am I thinking about this the right way?" before writing code is not a sign of weakness. It's a sign of someone who understands that software is built by teams, not individuals.

I used to think asking questions made me look junior. Now I think the most senior thing you can do is make sure everyone is aligned before anyone starts building.

Putting It All Together

Here's the full process in a quick reference:

Step	Action	Time
1. Define	Answer Who, What, Why	15 min
2. Scope	Draw resources + cut ruthlessly	20 min
3. Risk	Find the unknowns before they find you	15 min
4. Contract	Write what each endpoint accepts + returns	10 min/endpoint
5. Align	Show it to someone before coding	15 min

Total: roughly 1–2 hours depending on complexity.

That 1–2 hours will save you many times that in rework, confusion, and late-night debugging.

This Connects Back to Article 1

In my first article, I wrote about designing APIs with consistent error responses, proper status codes, and clean naming.

Those principles matter. But they only work if the foundation is right.

Planning is that foundation.

You can't consistently design good error responses if you didn't think through what errors were possible in the first place. You can't name things clearly if the scope isn't clear. You can't build something maintainable if no one agreed on what it should do.

Plan first. Then design. Then build.

What I'm Still Learning

Honestly — I'm still figuring out how much planning is "enough."

Too little and you're building the wrong thing. Too much and you're in planning paralysis, never shipping anything.

I don't have the answer yet. But I think the right amount of planning is: enough that your whole team can start without blocking each other.

What does your planning process look like? Do you have a system, or do you figure it out as you go? Drop it in the comments — I'm genuinely curious how more experienced engineers approach this. 🙏

Also

If you want a ready-made checklist to run through before building your next API, I put one together on GitHub:

👉 API Design Checklist — github.com/Bee34949/api-design-checklist

It's a living document — I update it as I learn. Contributions welcome.

Following along? I post about Backend Engineering and API Design — in both English 🇬🇧 and Thai 🇹🇭. See you in the next one. 🌱

# What I'm Learning About API Design in My First Month as a Backend Engineer

Wongsaphat Nakmuang — Tue, 02 Jun 2026 07:04:21 +0000

Thirty seconds into my first code review at work, my senior engineer pointed at my error response and said:

"This works. But if I'm a frontend dev consuming this at 2am trying to debug a production issue — this tells me nothing."

I had returned this:

{
  "success": false,
  "message": "Error"
}

That moment changed how I think about API design forever.

I'm Wongsaphat — a Junior Backend Engineer, 30 days into my first real job at INET (Internet Thailand). Before this, I spent years in university learning the theory. But theory and production are two very different things.

This article isn't a guide from an expert. It's an honest look at what I'm learning — the hard way — about designing APIs that other developers actually want to use.

Lesson 1: Error Responses Are a Product Feature

Before my job, I thought error handling meant wrapping code in try/catch and returning 500 if something broke.

I was wrong.

An error response is the first thing a frontend developer sees when something goes wrong. If it's vague, they have to come find you. If it's clear, they can fix it themselves.

What I was doing:

{
  "success": false,
  "message": "Error"
}

What I learned to do instead:

{
  "status": "error",
  "code": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Email is required"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters"
    }
  ]
}

The difference? The second one tells you exactly what went wrong and where. No guessing. No Slack messages asking "hey what does this error mean?"

The rule I now follow: Every endpoint in my API returns the same error structure. Always. No exceptions.

Lesson 2: Consistency Is More Important Than Cleverness

Early on, I was inconsistent without realizing it. Some endpoints returned:

{ "data": { "user": { ... } } }

Others returned:

{ "result": [ ... ] }

And some just returned the raw object:

{ "id": 1, "name": "Wongsaphat" }

All three "worked." But from a frontend developer's perspective, every endpoint behaved differently. They had to read the docs (or ask me) for every single endpoint.

What I do now — one response structure for everything:

// Success - single resource
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Wongsaphat",
    "email": "wongsaphat@example.com"
  }
}

// Success - list
{
  "status": "success",
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

// Error
{
  "status": "error",
  "code": 404,
  "message": "User not found"
}

Pick a structure. Use it everywhere. Your future teammates will thank you.

Lesson 3: Auth Is Not Something You Add Later

This one came from my professor, not my job — but I saw why it mattered once I started working.

When you're building fast, it's tempting to skip auth on endpoints because "I'll add it later." The problem is later never comes, or comes too late.

Here's what I now implement from day one — no exceptions:

JWT with expiry:

// ❌ Don't do this — no expiry
const token = jwt.sign({ userId: user.id }, SECRET_KEY)

// ✅ Do this — short-lived access token
const accessToken = jwt.sign(
  { userId: user.id },
  SECRET_KEY,
  { expiresIn: '15m' }
)

// ✅ Plus a refresh token for longer sessions
const refreshToken = jwt.sign(
  { userId: user.id },
  REFRESH_SECRET,
  { expiresIn: '7d' }
)

Return the right status code for auth failures:

// 401 = not authenticated (no token / invalid token)
// 403 = authenticated but no permission

// ❌ Using 403 for everything
if (!token) return res.status(403).json({ message: "Forbidden" })

// ✅ Correct
if (!token) return res.status(401).json({ message: "Authentication required" })
if (!hasPermission) return res.status(403).json({ message: "Access denied" })

Mixing up 401 and 403 seems small, but it breaks automated tools and confuses developers integrating with your API.

Lesson 4: Name Your Endpoints Like a Human, Not a Computer

This took me embarrassingly long to internalize.

// ❌ What I used to write
GET  /getUsers
POST /createUser
PUT  /updateUser/1
DELETE /deleteUser/1

// ✅ What I write now
GET    /users
POST   /users
PUT    /users/1
DELETE /users/1

The HTTP method already tells you the action. The URL should only describe the resource. Nouns, not verbs.

One more thing — be consistent with casing. Pick one and stick to it:

✅ /user-profiles     (kebab-case — recommended)
❌ /userProfiles      (camelCase — avoid in URLs)
❌ /user_profiles     (snake_case — inconsistent with REST conventions)

What I'm Still Figuring Out

I want to be honest — there's a lot I don't have answers to yet:

When should I use GraphQL vs REST? I understand both conceptually, but I haven't built enough real systems to have a strong opinion.
How do you version APIs without breaking existing clients? I know the theory (/api/v1/, /api/v2/), but handling it gracefully in practice is still unclear to me.
Rate limiting strategy — what's the right limit for different endpoint types?

If you have experience with any of these, I'd genuinely love to hear your approach in the comments.

Summary

Here's what changed in my thinking since starting work:

Before	After
Error = `{ "success": false }`	Error = structured, field-level details
Different response shape per endpoint	One consistent envelope for everything
Add auth "later"	Auth from day one, JWT with expiry
`/getUsers`, `/createUser`	`/users` with correct HTTP methods

None of this is revolutionary. But consistently doing these four things makes the difference between an API that developers enjoy working with — and one they complain about in Slack.

What's Next

I'm documenting everything I learn as I go. Next up:

REST vs GraphQL: My Honest Take as a Junior Dev — what I've actually used and what I think
5 API Design Mistakes I Made (And How I Fixed Them) — a more detailed breakdown of real errors from my first weeks

If this was useful, follow me here on Dev.to — I post regularly about Backend Engineering and API Design, in both English and Thai 🇹🇭

Also check out my API Design Checklist on GitHub — a living document I update as I learn.

Questions, disagreements, or things I got wrong? Drop them in the comments. I'm here to learn. 🌱