0Pricing
MongoDB Academy · Lección

Buenas prácticas de proyección para respuestas de API

Diseñará proyecciones que se ajusten a las estructuras de respuesta de las API REST, reduzcan el tamaño de la carga útil y protejan los campos sensibles.

Buenas prácticas de proyección para respuestas de API es una lección gratuita de MongoDB Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de MongoDB Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de MongoDB Academy incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

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.

Preguntas frecuentes

¿La lección «Buenas prácticas de proyección para respuestas de API» es gratis?

Sí — el texto completo de «Buenas prácticas de proyección para respuestas de API» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de MongoDB Academy, actualiza a CoddyKit PRO. El curso de MongoDB Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Buenas prácticas de proyección para respuestas de API»?

Diseñará proyecciones que se ajusten a las estructuras de respuesta de las API REST, reduzcan el tamaño de la carga útil y protejan los campos sensibles. Practicas MongoDB Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar MongoDB Academy?

No se requiere experiencia previa. MongoDB Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Buenas prácticas de proyección para respuestas de API»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de MongoDB Academy?

Sí. Cada lección de MongoDB Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Proyecciones de inclusión frente a exclusión
  2. Proyectar campos anidados y de arrays
  3. Las proyecciones de arrays $ y $elemMatch
  4. Buenas prácticas de proyección para respuestas de API
← Volver a MongoDB Academy