Operaciones CRUD en APIs REST con Postman

Contenido del curso

Fundamentos y Primer CRUD

Base de Datos y Persistencia con TypeORM

Autenticación y Autorización

Tu API Completa

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0023:37

Operaciones CRUD en APIs REST con Postman

Curso de Backend con NestJS

Clase 4 de 35

Clase 4 / 35

Recursos

Construir una API REST completa requiere ir más allá de leer datos: necesitas crear, actualizar y eliminar recursos. Aquí verás cómo implementar endpoints CRUD en NestJS usando los decoradores @Post, @Delete y @Body, y cómo probarlos con Postman para validar tu lógica de negocio.

Qué son las CRUD operations y por qué importan en una API

Las operaciones CRUD son las cuatro acciones básicas sobre cualquier recurso: create, read, update y delete. En tu API estas acciones permiten que los datos se muten según lo necesite el negocio, no solo que se consulten.

Hasta ahora solo teníamos la parte de read con dos endpoints GET: uno para obtener todos los usuarios y otro para obtener uno específico por ID. Faltan crear, actualizar y eliminar, que son los que realmente le dan vida a una API [00:10].

¿Qué significa CRUD? Son las siglas de create, read, update, delete. Representan las cuatro operaciones básicas que toda API debe ofrecer sobre sus recursos.

Por qué usar Postman en lugar del navegador para probar endpoints

El navegador funciona para hacer peticiones GET sencillas, pero se queda corto cuando necesitas enviar datos en el cuerpo o cambiar el método HTTP. Por eso entra Postman, una herramienta pensada específicamente para probar REST APIs [01:10].

Otra alternativa válida es Insomnia, que cumple la misma función. En el flujo de trabajo dentro de Postman vas a:

Crear una colección con el nombre de tu proyecto, por ejemplo Blog API.
Agregar requests dentro de la colección y elegir el protocolo correcto.
Pegar el endpoint con el puerto en el que corre tu servidor.
Guardar notas internas para recordar qué hace cada request.

Con esto tienes un espacio organizado para probar cada método sin depender del navegador.

Cómo crear un endpoint POST con el decorador Body en NestJS

Para crear usuarios necesitas un método POST que reciba la información en el body del request, no como parámetro en la URL [05:30]. La firma del endpoint es la misma que el GET (/users), pero el protocolo cambia, y eso es lo interesante de REST: un mismo endpoint hace cosas distintas según el método HTTP.

En el controlador agregas el decorador @Post() y dentro del método usas @Body() para leer el cuerpo del request. Puedes tipar ese body como User para tener autocompletado en TypeScript, aunque ese tipado no valida los datos en tiempo de ejecución.

La lógica para guardar el usuario es un simple push al array en memoria. Pero ojo: el método push de JavaScript devuelve la nueva longitud del array, no el elemento insertado. Por eso lo correcto es retornar el body recibido, que es la información que quedó persistida [09:45].

¿Qué es el body en una petición HTTP? Es el cuerpo del request donde envías datos estructurados, normalmente en formato JSON. Se usa en métodos como POST, PUT y PATCH para mandar la información que el servidor debe procesar.

Cómo enviar un POST desde Postman con formato JSON

Dentro de Postman duplicas un endpoint existente, cambias el método a POST y vas a la pestaña Body. Eliges la opción raw y formato JSON. Ahí escribes el objeto con las llaves obligatorias del JSON: id, name y email. Al enviar el request, NestJS responde automáticamente con un status code 201, que es el código estándar para indicar que un recurso fue creado correctamente [11:20].

Esta es una de esas ventajas silenciosas de NestJS: aplica buenas prácticas REST por defecto, sin que tengas que configurar nada.

Cómo eliminar usuarios con el método DELETE en NestJS

El endpoint DELETE se parece mucho a un GET con parámetro: recibe el ID del usuario en la URL y ejecuta la lógica de borrado. La diferencia está en el decorador @Delete() y en lo que retorna [13:50].

Para la respuesta hay dos enfoques comunes:

Devolver la información del usuario eliminado.
Devolver un mensaje de estado tipo { message: 'user deleted' }.

La segunda opción es más limpia y comunica mejor la intención. Para implementarlo en JavaScript hay varias rutas, pero la más práctica es usar findIndex para localizar la posición del usuario y luego splice para eliminarlo en una sola iteración.

Por qué validar la existencia antes de eliminar

No tiene sentido responder user deleted si el usuario nunca existió. Por eso primero buscas con findIndex: si la posición es -1, retornas un mensaje de user not found. Si existe, ejecutas el splice y confirmas la eliminación [16:30].

Este patrón de validación previa lo vas a repetir mucho en tus controladores, y más adelante verás cómo evitar duplicar ese código.

Por qué los datos se pierden con el live reloading en desarrollo

Un detalle importante mientras desarrollas: los usuarios viven en un array en memoria, no en una base de datos. Cada vez que guardas un cambio en el código, el servidor reinicia gracias al live reloading y el array vuelve a su estado inicial con los tres usuarios por defecto [10:15].

No hay persistencia real todavía, así que cualquier creación o eliminación que hagas se pierde al recargar. Más adelante conectarás una base de datos para resolverlo, pero por ahora tenlo presente para no confundirte cuando los datos parezcan desaparecer.

Cuándo devolver un status code 200, 201 o 404

Los status codes le dicen al cliente cómo terminó la operación, y elegir el correcto es parte de hacer una API decente:

200: la petición fue exitosa, típico en GET y DELETE.
201: se creó un recurso nuevo, estándar en POST. NestJS lo aplica automáticamente.
404: el recurso o endpoint no fue encontrado. Node.js lo devuelve solo cuando la ruta no existe.

Cuando devuelves user not found con un status 200 estás mintiendo: la operación no salió bien. Más adelante ajustarás esos códigos para que reflejen la realidad, pero ya tienes la base para entender por qué importan.

Reto: cómo generar IDs automáticos al crear usuarios

Ahora mismo el cliente envía el id manualmente en el body, lo cual es frágil y propenso a duplicados. El reto es que solo envíes name y email, y el ID se genere automáticamente.

Tienes dos caminos posibles:

Usar la longitud actual del array más uno como nuevo ID secuencial.
Generar un string aleatorio que sirva como identificador único.

¿Cómo lo resolverías tú? Déjame tu propuesta en los comentarios.

Juan Diego Mejia Maestre

Hace 6 meses

1. El Servicio (users.service.ts)

Aquí centralizamos la lógica. Para los filtros, usamos una lógica flexible sobre el array en memoria.

TypeScript

import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class UsersService {
  private users = [
    { id: 1, name: 'Juan Diego', email: 'juan@example.com', role: 'admin' },
    { id: 2, name: 'Andrés', email: 'andres@example.com', role: 'user' },
  ];

  // GET ALL con Filtros
  findAll(name?: string, role?: string) {
    let results = [...this.users];

    if (name) {
      results = results.filter(u => u.name.toLowerCase().includes(name.toLowerCase()));
    }
    if (role) {
      results = results.filter(u => u.role === role);
    }
    return results;
  }

  // GET by ID
  findOne(id: number) {
    const user = this.users.find(u => u.id === id);
    if (!user) throw new NotFoundException(`Usuario con ID ${id} no encontrado`);
    return user;
  }

  // POST (Crear)
  create(userData: any) {
    const newId = this.users.length > 0 ? Math.max(...this.users.map(u => u.id)) + 1 : 1;
    const newUser = { id: newId, ...userData };
    this.users.push(newUser);
    return newUser;
  }

  // PUT (Actualizar)
  update(id: number, updateData: any) {
    const index = this.users.findIndex(u => u.id === id);
    if (index === -1) throw new NotFoundException(`Imposible actualizar: ID ${id} inexistente`);
    
    // Fusionamos los datos actuales con los nuevos
    this.users[index] = { ...this.users[index], ...updateData };
    return this.users[index];
  }

  // DELETE (Eliminar)
  remove(id: number) {
    const index = this.users.findIndex(u => u.id === id);
    if (index === -1) throw new NotFoundException(`Imposible eliminar: ID ${id} inexistente`);
    
    const deleted = this.users.splice(index, 1);
    return { message: 'Usuario eliminado con éxito', user: deleted[0] };
  }
}

2. El Controlador (users.controller.ts)

Aquí definimos los decoradores para capturar los datos de la URL (@Param), del cuerpo (@Body) y de la consulta (@Query).

TypeScript

import { Controller, Get, Post, Put, Delete, Body, Param, Query, ParseIntPipe } from '@nestjs/common';
import { UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  // GET /users?name=Juan&role=admin
  @Get()
  getUsers(
    @Query('name') name?: string,
    @Query('role') role?: string
  ) {
    return this.usersService.findAll(name, role);
  }

  @Get(':id')
  getUserById(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }

  @Post()
  createUser(@Body() body: any) {
    return this.usersService.create(body);
  }

  @Put(':id')
  updateUser(
    @Param('id', ParseIntPipe) id: number, 
    @Body() body: any
  ) {
    return this.usersService.update(id, body);
  }

  @Delete(':id')
  deleteUser(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.remove(id);
  }
}

📋 Resumen de Endpoints para Postman

OperaciónMétodoURLDescripción

Listar

GET

/users

Obtiene todos los usuarios.

Filtrar

GET

/users?role=admin

Filtra por query params.

Buscar

GET

/users/1

Busca por ID.

Crear

POST

/users

Envía JSON en el Body.

Editar

PUT

/users/1

Actualiza parcialmente o total.

Borrar

DELETE

/users/1

Elimina el recurso.

💡 Notas para Obsidian

🎯 Cómo NestJS recibe datos (Decoradores)

Los decoradores son "etiquetas" que le dicen a NestJS exactamente de dónde sacar la información de la petición del cliente.

@Query('llave'): Se usa para filtrar o buscar. Son los datos que van después del signo ? en la URL (ej: /productos?color=rojo). Si el usuario no envía el parámetro, NestJS lo deja como undefined, lo que te permite hacer un simple if(color) en tu lógica.
@Param('id'): Se usa para identificar un recurso específico. Es parte de la ruta de la URL (ej: /productos/5).
- Truco: Usa siempre ParseIntPipe con este decorador para que NestJS convierta el texto de la URL en un número automáticamente.
@Body(): Se usa para enviar objetos completos, generalmente en formato JSON. Es lo que usas cuando creas o editas un usuario. Contiene toda la "carga útil" o información pesada de la petición.
@Headers(): Se usa para metadatos, como tokens de autenticación o el tipo de contenido que se está enviando.

🛠️ Los 4 Pilares del CRUD (Métodos HTTP)

Cada método define la intención de lo que quieres hacer con los datos:

GET (Leer)

Es el método por defecto. Se usa para pedir información al servidor sin modificar nada.

Tip: Puedes tener dos GET: uno general (/users) que devuelva una lista filtrada con @Query, y uno específico (/users/:id) que use @Param para traer un solo registro.

POST (Crear)

Se usa para enviar información nueva al servidor.

Detalle técnico: Por estándar, NestJS responde con un código 201 (Creado). Es buena práctica que este método devuelva el objeto recién creado (incluyendo su nuevo ID) para confirmarle al cliente que todo salió bien.

PUT (Actualizar)

Se usa para modificar un recurso que ya existe.

Lógica: Normalmente combinas @Param (para saber a quién editar) y @Body (para saber qué datos nuevos poner). En el servicio, usas el Spread Operator ... para mezclar los datos viejos con los nuevos sin borrar lo que no se envió.

DELETE (Eliminar)

Se usa para remover un recurso.

Clave: Solo suele necesitar el @Param('id').
Truco de validación: Antes de borrar, intenta buscar el elemento con un find. Si no existe, lanza un NotFoundException de inmediato para avisarle al usuario que está intentando borrar algo que ya no está.

💡 El Truco Maestro: "Fail Early"

En NestJS, la mejor forma de escribir servicios limpios es fallar rápido. Si vas a buscar, editar o borrar algo por ID, lo primero que debe hacer tu código es verificar si existe. Si no existe, lanza el error ahí mismo. Así, el resto de tu función queda limpia y sin necesidad de usar muchos else.