backend-fundamentals

"APIs are contracts. Break them, and you break trust."

When to Apply

Activate this skill when reviewing:

• API route handlers
• Express/Fastify/Hono middleware
• Database queries and models
• Authentication/authorization logic
• Server-side business logic

---

Review Checklist

API Design

• [ ] RESTful: Do routes follow REST conventions? (GET for read, POST for create, etc.)
• [ ] Naming: Are endpoints nouns, not verbs? (/users not /getUsers)
• [ ] Versioning: Is API versioned for future changes? (/api/v1/)
• [ ] Status Codes: Are correct HTTP status codes returned?

Separation of Concerns

• [ ] Routes: Do routes only handle HTTP concerns (req/res)?
• [ ] Controllers: Is business logic in controllers/services, not routes?
• [ ] Services: Is data access abstracted from business logic?
• [ ] Models: Are models responsible only for data shape/validation?

Error Handling

• [ ] Try/Catch: Are async operations wrapped properly?
• [ ] Error Responses: Are errors returned with proper status codes?
• [ ] Logging: Are errors logged with context?
• [ ] No Leaks: Are internal errors hidden from clients?

Security

• [ ] Input Validation: Is ALL input validated before use?
• [ ] Authentication: Are protected routes actually protected?
• [ ] Authorization: Can users only access their own data?
• [ ] Rate Limiting: Are endpoints protected from abuse?

---

Common Mistakes (Anti-Patterns)

1. Fat Routes

❌ app.post('/users', async (req, res) => {
     // 100 lines of validation, business logic, DB queries
   });

✅ app.post('/users', validateUser, userController.create);

2. No Input Validation

❌ const { email } = req.body;
   await db.query(`SELECT * FROM users WHERE email = '${email}'`);

✅ const { email } = validateBody(req.body, userSchema);
   await User.findByEmail(email); // parameterized

3. Wrong Status Codes

❌ res.status(200).json({ error: 'Not found' });

✅ res.status(404).json({ error: 'User not found' });

4. Leaking Internal Errors

❌ catch (error) {
     res.status(500).json({ error: error.message, stack: error.stack });
   }

✅ catch (error) {
     logger.error('User creation failed', { error, userId });
     res.status(500).json({ error: 'Something went wrong' });
   }

---

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Architecture: "If I wanted to switch from Express to Fastify, what would need to change?"
2. Validation: "What happens if someone sends malformed JSON?"
3. Auth: "How do you know this user owns this resource?"
4. Errors: "What does the client see when the database is down?"
5. Testing: "How would you test this endpoint in isolation?"

---

HTTP Status Code Reference

| Code | When to Use | |------|-------------| | 200 | Success (with body) | | 201 | Created (after POST) | | 204 | Success (no content, after DELETE) | | 400 | Bad request (validation failed) | | 401 | Unauthorized (not logged in) | | 403 | Forbidden (logged in but not allowed) | | 404 | Not found | | 409 | Conflict (duplicate resource) | | 500 | Server error (hide details from client) |

---

Architecture Layers

Request → Route → Controller → Service → Repository → Database
                     ↓
              Middleware (auth, validation, logging)

| Layer | Responsibility | |-------|----------------| | Route | HTTP verbs, paths, middleware chain | | Controller | Request/response handling, calling services | | Service | Business logic, orchestration | | Repository | Data access, queries |

---

Red Flags to Call Out

| Flag | Question to Ask | |------|-----------------| | SQL in route handler | "Should data access be in a separate layer?" | | No try/catch on async | "What happens if this fails?" | | req.body used directly | "What if someone sends unexpected fields?" | | Hardcoded secrets | "How would this work in production?" | | No pagination on list endpoints | "What if there are 10,000 records?" |