0Pricing
MongoDB Academy · Lesson

Projection Best Practices for API Responses

Learners will design projections that align with REST API response shapes, reducing payload size and protecting sensitive fields.

Projection Best Practices for API Responses is a free MongoDB Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Align Projections With API Response Shapes

Every REST or GraphQL endpoint your application exposes has a defined response shape. The ideal MongoDB projection returns exactly the fields that shape requires—no more, no less. When your projection mirrors your API response contract, you avoid two common anti-patterns: over-fetching (returning fields the endpoint never sends) and under-fetching (returning fields that force a second query).

Define Projection Constants

Hardcoding projection objects inline in every query leads to duplication and drift over time. Define projection constants alongside your data access functions or repositories. If the API response shape changes, you update one constant rather than hunting for every query in the codebase.

// projections.js — centralised projection definitions
export const USER_PUBLIC = { _id: 0, username: 1, avatarUrl: 1, createdAt: 1 };
export const USER_PROFILE = { _id: 0, username: 1, email: 1, bio: 1, avatarUrl: 1 };
export const USER_ADMIN = { _id: 0, username: 1, email: 1, role: 1, lastLoginAt: 1, isActive: 1 };

// Usage
const user = await db.collection('users').findOne({ username: 'alice' }, { projection: USER_PROFILE });

Never Return Sensitive Fields to Clients

Fields like passwordHash, totpSecret, apiKey, ssn, and paymentMethodToken should never appear in API responses. Define a secure base projection that excludes them by default, and only fetch them in internal service calls that specifically require them. Apply the principle of least privilege at the data layer.

// Always exclude sensitive fields from user queries
const SECURE_USER_BASE = {
  passwordHash: 0,
  totpSecret: 0,
  resetToken: 0
};

// All user API responses go through this projection
const user = await db.collection('users').findOne(
  { _id: userId },
  { projection: SECURE_USER_BASE }
);

// Result never contains passwordHash or totpSecret

List Endpoints: Project Only Summary Fields

List endpoints (e.g., GET /products) typically return a summary of each item, not the full document. A product list might show name, price, thumbnailUrl, and rating—not the full description, specifications array, or reviews. Using a tight projection for list queries can reduce payload size by 90% when full documents contain large text or arrays.

const PRODUCT_SUMMARY = {
  _id: 0,
  slug: 1,
  name: 1,
  price: 1,
  thumbnailUrl: 1,
  rating: 1,
  reviewCount: 1
};

// GET /products — lightweight list query
const products = await db.collection('products')
  .find({ category: 'electronics', isActive: true })
  .projection(PRODUCT_SUMMARY)
  .sort({ rating: -1 })
  .limit(20)
  .toArray();

Detail Endpoints: Project the Full Object

Detail endpoints (e.g., GET /products/:slug) return a richer view of a single document. Even here, consider excluding internal-only fields. You might project all public fields while suppressing internal cost price, supplier contact details, or inventory source system IDs that clients should not see.

const PRODUCT_DETAIL = {
  supplierCost: 0,       // internal — never expose to clients
  warehouseLocation: 0,  // internal
  syncedFromErpAt: 0     // internal audit field
};

// GET /products/:slug — rich detail query
const product = await db.collection('products').findOne(
  { slug: req.params.slug, isActive: true },
  { projection: PRODUCT_DETAIL }
);

Use Projections in Aggregation Pipelines Too

Projection best practices extend to the aggregation pipeline. Place a $project stage after $match and before expensive stages like $lookup or $unwind to reduce the document size flowing through the pipeline. Smaller documents in the pipeline mean less memory and CPU usage on the server.

db.orders.aggregate([
  { $match: { status: 'shipped', customerId: ObjectId('c1') } },
  // Project early to reduce document size before $lookup
  { $project: { total: 1, createdAt: 1, customerId: 1, _id: 0 } },
  {
    $lookup: {
      from: 'customers',
      localField: 'customerId',
      foreignField: '_id',
      as: 'customer'
    }
  }
]);

Projections and API Versioning

When you add new fields to MongoDB documents, old API clients may not expect them. Using strict inclusion projections (listing exactly the fields to return) means new document fields are invisible to existing API consumers until you explicitly add them to the projection. This gives you a natural versioning boundary: update the projection when you update the API version.

// v1 projection — stable contract for existing clients
export const USER_V1 = { _id: 0, username: 1, email: 1 };

// v2 projection — includes new avatarUrl and bio fields
export const USER_V2 = { _id: 0, username: 1, email: 1, avatarUrl: 1, bio: 1 };

Test That Projections Match Response Schemas

Write unit tests that assert the MongoDB projection object matches your API response schema (e.g., a Joi schema or a TypeScript type). This prevents the common bug where a developer adds a field to the API response type but forgets to include it in the projection—the field comes back as undefined in production while passing TypeScript type checks.

// Example test asserting projection covers all required response fields
const USER_RESPONSE_FIELDS = ['username', 'email', 'avatarUrl'];
const projection = { username: 1, email: 1, avatarUrl: 1, _id: 0 };

for (const field of USER_RESPONSE_FIELDS) {
  if (projection[field] !== 1) {
    throw new Error('Projection missing field: ' + field);
  }
}
console.log('Projection covers all required response fields');

Avoiding Projection Mismatch in Mongoose

Mongoose schemas with select: false on a field prevent that field from appearing in any query result unless explicitly re-included. Combine this with schema-level virtuals to compute derived values without storing them. Together, these tools let you enforce a secure default projection at the model level, reducing the chance of accidentally leaking data through a missing query projection.

const userSchema = new mongoose.Schema({
  username: String,
  email:    String,
  // Excluded from all queries by default — must explicitly use +passwordHash
  passwordHash: { type: String, select: false },

  // Virtual — computed, not stored, never in DB
  get displayName() { return this.username.toUpperCase(); }
});
userSchema.virtual('displayName').get(function() {
  return this.username.toUpperCase();
});

Monitoring Projection Efficiency

Use explain('executionStats')

to verify that your projections are working as intended. Look at the nReturned vs keysExamined and docsExamined ratio. If docsExamined equals the number of matched documents (not zero), your projection is not covered by an index but is still correct—you can weigh whether adding a covering index is worth the maintenance cost.

const result = await db.collection('users').find(
  { role: 'admin' },
  { projection: { username: 1, email: 1, _id: 0 } }
).explain('executionStats');

console.log('Docs examined:', result.executionStats.totalDocsExamined);
console.log('Keys examined:', result.executionStats.totalKeysExamined);
console.log('Docs returned:', result.executionStats.nReturned);

Summary: Projection Best Practice Checklist

Apply this checklist to every MongoDB query in your API:

  • Define named projection constants — one per endpoint or response shape
  • Use inclusion mode for API responses — list exactly what you need
  • Always exclude sensitive fields — passwordHash, tokens, internal IDs
  • Use tight projections for list endpoints — summary only, no large bodies
  • Place $project early in aggregation pipelines — reduce data flowing downstream

Quick Check

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

Lesson Recap

In this lesson you learned: projection constants should be defined per API endpoint to prevent drift, sensitive fields must always be excluded from client-facing queries, and placing $project early in aggregation pipelines reduces memory pressure. Next up we explore sorting and pagination to order and page through large result sets efficiently.

Frequently asked questions

Is the “Projection Best Practices for API Responses” lesson free?

Yes — the full text of “Projection Best Practices for API Responses” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.

What will I learn in “Projection Best Practices for API Responses”?

Learners will design projections that align with REST API response shapes, reducing payload size and protecting sensitive fields. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start MongoDB Academy?

No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Projection Best Practices for API Responses” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this MongoDB Academy lesson?

Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Inclusion vs Exclusion Projections
  2. Projecting Nested and Array Fields
  3. The $ and $elemMatch Array Projections
  4. Projection Best Practices for API Responses
← Back to MongoDB Academy