Stop Returning 200 OK When Your API Explodes

The “Success: False” Anti-Pattern

// DO THIS INSTEAD
app.get('/api/v1/users/:id', async (req, res, next) => {
  try {
    const user = await db.findUser(req.params.id);
    
    if (!user) {
      // 404 is semantic. It means "Not Found". Use it.
      return res.status(404).json({ 
        error: {
          code: 'USER_NOT_FOUND',
          message: 'The requested user ID does not exist.'
        }
      });
    }

    return res.json({ data: user });
  } catch (err) {
    // Pass to global error handler
    next(err);
  }
});

Structuring for the Consumer

// frontend-api.js
// A generic fetch wrapper for our consistent API structure

async function fetchData(endpoint) {
  const response = await fetch(endpoint);
  const json = await response.json();

  // If the status isn't 2xx, throw an error with the server's message
  if (!response.ok) {
    throw new Error(json.error?.message || HTTP Error ${response.status});
  }

  return json.data;
}

The “N+1” Query Trap in Routes

// FASTER: Parallel execution
app.get('/api/v1/posts', async (req, res) => {
  const posts = await db.getPosts();
  
  // Fetch all authors in parallel
  const postsWithAuthors = await Promise.all(
    posts.map(async (post) => {
      const author = await db.getUser(post.authorId);
      return { ...post, author };
    })
  );
  
  res.json({ data: postsWithAuthors });
});

Versioning Is Not Optional

A Note on “Rest” vs “Pragmatism”