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

Source: Dev.to

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. 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. 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. 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?” 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. 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. 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. 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. 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. 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. 🙏 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. 🌱