Common API Relationship Mistakes in MongoDB (and How to Fix Them)

Common API Relationship Mistakes in MongoDB

Handling relationships in APIs has predictable failure modes. Here are common mistakes and fixes.

Mistake 1: N+1 Queries

You loop over posts and call User.findById for each author. Fix: use populate to do it in 2 queries.

Mistake 2: Populating Without Select

You do .populate('authorId') and return the entire author document, including passwordHash. Fix: always populate with a select: .populate('authorId', 'firstName lastName photoUrl').

Mistake 3: Deep Nested populate

You populate three levels deep. Each level is an extra query. Fix: side-load or denormalize. Limit populate to one level.

Mistake 4: Storing Refs as Strings

You store authorId as a string instead of ObjectId. populate breaks. Fix: use mongoose.Schema.Types.ObjectId with ref.

Mistake 5: No Index on the Ref Field

You query by authorId but did not index it. MongoDB scans every document. Fix: index ref fields. Use compound indexes with sort fields.

Mistake 6: Embedding Unbounded Arrays

You store all messages in a connection document. The array grows until the document hits 16MB. Fix: use refs and a separate collection for large N.

Mistake 7: Not Handling null populate

You populate a ref that was deleted. The field is null. Your code crashes. Fix: check for null before accessing the populated field.

Mistake 8: Denormalizing Without a Plan for Staleness

You copy the author's name on the post. The author changes their name. The post shows the old name forever. Fix: decide whether to update on change or accept staleness. Document the decision.

Mistake 9: No Cascade Delete

You delete a user but leave their posts and messages. Fix: cascade delete. Delete related documents in the same handler (or in a transaction).

Mistake 10: Returning Internal Fields

You return the entire post document, including internal version fields and the raw authorId. Fix: use a serializer (DTO) that picks only the fields the client needs.

The Takeaway

Common API relationship mistakes: N+1 queries, populating without select, deep nested populate, storing refs as strings, no index on ref fields, embedding unbounded arrays, not handling null populate, denormalizing without a staleness plan, no cascade delete, and returning internal fields. Fix them on day one.