Express Endpoint Skill

Crea un nuevo endpoint Express siguiendo el patron del proyecto Ocralis.

When to Activate

• Crear un nuevo endpoint REST en el backend
• Agregar operaciones CRUD para un recurso
• Integrar un nuevo modulo con validacion y autenticacion
• Extender un controller existente con nuevos handlers

Patron Completo

1. Controller (controllers/{modulo}.controller.js)

import { prisma } from "../prismaClient.js";
import logger from "../utils/logger.js";
import { z } from "zod";

// Schema de validacion Zod
const createSchema = z.object({
  nombre: z.string().min(1, "Nombre requerido"),
  email: z.string().email("Email invalido"),
  // campos con tipos y validaciones segun el recurso
});

export const create = async (req, res) => {
  try {
    // 1. Validar input con Zod
    const validated = createSchema.parse(req.body);

    // 2. Obtener usuario autenticado
    const usuario = req.user;

    // 3. Logica de negocio (llamar servicio si es externo)
    const result = await prisma.model.create({
      data: { ...validated, usuarioId: usuario.id },
    });

    // 4. Respuesta consistente
    res.status(201).json({ success: true, data: result });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({
        success: false,
        error: "Datos invalidos",
        details: error.errors,
      });
    }
    logger.error(error, "Error en create");
    res.status(500).json({ success: false, error: "Error interno del servidor" });
  }
};

export const list = async (req, res) => {
  try {
    const usuario = req.user;
    const items = await prisma.model.findMany({
      where: { usuarioId: usuario.id },
      orderBy: { createdAt: "desc" },
    });
    res.json({ success: true, data: items });
  } catch (error) {
    logger.error(error, "Error en list");
    res.status(500).json({ success: false, error: "Error interno del servidor" });
  }
};

export const getById = async (req, res) => {
  try {
    const { id } = req.params;
    const item = await prisma.model.findUnique({
      where: { id: parseInt(id) },
    });
    if (!item) {
      return res.status(404).json({ success: false, error: "No encontrado" });
    }
    res.json({ success: true, data: item });
  } catch (error) {
    logger.error(error, "Error en getById");
    res.status(500).json({ success: false, error: "Error interno del servidor" });
  }
};

export const update = async (req, res) => {
  try {
    const { id } = req.params;
    const validated = updateSchema.parse(req.body);
    const item = await prisma.model.update({
      where: { id: parseInt(id) },
      data: validated,
    });
    res.json({ success: true, data: item });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({
        success: false,
        error: "Datos invalidos",
        details: error.errors,
      });
    }
    logger.error(error, "Error en update");
    res.status(500).json({ success: false, error: "Error interno del servidor" });
  }
};

export const remove = async (req, res) => {
  try {
    const { id } = req.params;
    await prisma.model.delete({ where: { id: parseInt(id) } });
    res.json({ success: true, data: { message: "Eliminado correctamente" } });
  } catch (error) {
    logger.error(error, "Error en remove");
    res.status(500).json({ success: false, error: "Error interno del servidor" });
  }
};

2. Routes (routes/{modulo}.routes.js)

import express from "express";
import { create, list, getById, update, remove } from "../controllers/{modulo}.controller.js";
import { authenticateToken } from "../middleware/auth.middleware.js";

const router = express.Router();

// Aplicar auth a todas las rutas del modulo
router.use(authenticateToken);

router.post("/", create);
router.get("/", list);
router.get("/:id", getById);
router.put("/:id", update);
router.delete("/:id", remove);

export default router;

3. Registrar en app.js

import moduloRoutes from "./routes/{modulo}.routes.js";
app.use("/api/{modulo}", moduloRoutes);

4. Service externo (opcional) (services/{modulo}.service.js)

Solo crear si el endpoint necesita integrar con APIs externas (SALTRA, GCS, Gemini, etc.). Para operaciones CRUD puras con Prisma, la logica va directamente en el controller.

Convenciones del Proyecto

Concepto	Convencion
Modulos	ES Modules (import/export, no require)
Prisma	import { prisma } from "../prismaClient.js"
Auth	req.user contiene el usuario autenticado (set por authenticateToken)
Respuestas	{ success: true/false, data: ..., error: "mensaje" }
Logging	Pino: logger.info, logger.error, logger.debug
Validacion	Zod inline en el controller
IDs	Integer autoincrement en Prisma
Errores Zod	Status 400 con details: error.errors
Errores 404	{ success: false, error: "No encontrado" }
Errores 500	{ success: false, error: "Error interno del servidor" }

Checklist

• Controller creado con try/catch y logging en cada handler
• Schema Zod para validacion de input (create y update)
• Routes con authenticateToken middleware
• Registrado en app.js con prefijo /api/{modulo}
• Service creado si hay integracion externa
• Respuestas consistentes (success/data/error)
• IDs parseados con parseInt() en params
• 404 para recursos no encontrados
• Actualizar README.md y README_CONTROLLERS.md