API First con IA: construye CRUD sin codificar

Cursos Empresas Blog Live Conf Precios

Contenido del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

19
Proteger endpoints con JWT en OpenAPI
07:40 min

Tomar examen

API First con IA: construye CRUD sin codificar

Resumen

Construir una API funcional sin escribir código manualmente es posible cuando combinas el enfoque API First, la especificación de OpenAPI y herramientas de inteligencia artificial como Cursor o ChatGPT. Aquí descubrirás cómo aprovechar un prompt bien estructurado para que la IA traduzca tu contrato en lógica funcional, depure errores y migre tu API a otros lenguajes en minutos.

Cómo le pides a Cursor que construya la lógica de tu API

El punto de partida es abrir un chat con el agente dentro del editor y referenciar el archivo OpenAPI como contexto. La instrucción debe ser específica: indicar qué recurso trabajar, dónde insertar el código y cómo simular los datos.

En la práctica, el prompt fue: "Con los últimos cambios en OpenAPI para productos, crea la lógica necesaria en index.js y simula la base de datos con un array simple". Con esa frase, Cursor entiende el contexto completo del proyecto, los paquetes instalados y la estructura previa, y empieza a generar los endpoints en Express.js.

¿Qué es API First? Es un enfoque donde primero defines el contrato de tu API en una especificación como OpenAPI y, a partir de ese contrato, construyes la lógica del servidor y del cliente.

Qué hacer si no tienes Cursor a la mano

No todos trabajan con un editor con agente integrado, y eso no es un problema. Puedes copiar el archivo OpenAPI completo y pegarlo en ChatGPT, Gemini o DeepSeek, y pedirle que analice el recurso y construya la API.

Ahí viene lo interesante: en el ejemplo se le pidió cambiar de lenguaje a Python con FastAPI. La IA leyó la especificación, listó los paquetes necesarios e implementó clases como HelloResponse, los endpoints de productos, usuarios y rating, todo siguiendo el contrato original [02:15].

La diferencia clave: ChatGPT no tiene contexto del proyecto completo, así que trabaja de forma aislada. Cursor sí entiende los archivos y dependencias, por eso inserta el código directamente donde corresponde.

Cómo se ve el código generado para productos

Una vez aceptados los cambios, conviene revisar lo que la IA produjo antes de seguir. En el ejemplo, generó:

Una base de datos simulada como array con dos productos iniciales: una laptop en categoría electronics y el libro Clean Code anidado en libros de programación.
Un endpoint POST para crear productos con validaciones según el esquema.
Un GET para listar productos completos.
Un GET por product ID para buscar uno específico.
Un PUT para actualizar productos validando contra la base simulada.
Un DELETE para eliminar por ID.

Cada endpoint respeta los nombres de variables, tipos y categorías predefinidas que se declararon en el contrato OpenAPI. La IA incluso eligió correctamente la categoría electronics para la laptop porque entendió las restricciones del esquema.

Por qué conviene reiniciar el servidor tras cambios grandes

Cuando hay varios endpoints nuevos, reiniciar con npm run dev ayuda a que el servidor reconozca toda la documentación desde cero. Si algo no quedó bien definido, el error aparece de inmediato y no después, en producción [06:40].

Cómo usar Swagger para validar la API construida

La documentación con Swagger se genera automáticamente desde la especificación OpenAPI, así que ya tienes una interfaz lista para probar cada endpoint sin escribir un cliente HTTP. Verás botones para crear, listar, obtener por ID, actualizar y eliminar productos.

Al ejecutar el GET de listar productos, apareció un internal server error. Aquí entra otra ventaja del enfoque: el middleware de OpenAPI Validator detecta inconsistencias entre el código y el contrato, y entrega pistas claras del problema.

¿Para qué sirve OpenAPI Validator? Es un middleware que valida en tiempo real que las peticiones y respuestas de tu API cumplan con la especificación OpenAPI definida en el contrato.

Cómo depurar errores con ayuda de la IA

Copiar el error completo y pegarlo en el chat del agente permitió identificar la falla: faltaba el tipo object en los items del array. Era un detalle del contrato, no de la lógica en Express.js, pero al estar capturado por el middleware, bloqueaba la respuesta.

Después de corregir la especificación, reiniciar el servidor y refrescar Swagger, el listado de productos respondió correctamente con los dos elementos iniciales.

Cómo probar el flujo completo CRUD desde Swagger

Con la API funcional, el siguiente paso es recorrer el ciclo completo:

Crear producto: en el POST, Swagger ofrece una estructura base que puedes editar. Se creó un MacBook con precio 999 y categoría electronics. La respuesta devolvió un ID generado por timestamp.
Listar productos: el GET mostró los tres elementos, incluyendo el recién creado.
Obtener por ID: aquí surgió un detalle importante. El ID no era 3, sino un valor numérico largo basado en la fecha. Al usar el ID correcto, el producto apareció sin problema.
Actualizar por ID: se cambió el nombre a MacBook Pro y el precio a 1.200. La respuesta confirmó la actualización.
Eliminar por ID: la API devolvió un código 204, indicando éxito sin contenido. El listado final mostró solo los dos productos originales.

Qué significan los códigos de estado HTTP que viste

200: respuesta exitosa.
300: redirección.
400: error en la lógica del cliente.
500: error del servidor.
204: éxito sin contenido devuelto, típico de un DELETE.

Entender estos códigos te ayuda a interpretar lo que tu API responde y a diseñar el manejo de errores en el cliente.

Por qué este flujo cambia tu forma de construir APIs

El ejercicio completo demuestra que partiendo de un esquema bien definido (qué campos tiene un producto, sus reglas, sus mínimos), la inteligencia artificial puede generar la lógica en Express.js, migrarla a FastAPI con Python e incluso depurar errores de tipado en el contrato.

No escribiste prácticamente código manual, y aun así tienes una API funcional con CRUD completo, documentación interactiva y validación automática.

El reto ahora es replicar el proceso con un recurso distinto: diseña un esquema de usuario con perfil, avatar y otros campos, llévalo a OpenAPI y pídele a la IA que lo construya en Django con Python o en otro stack. ¿Qué resultado obtuviste? Cuéntalo en los comentarios.

William Serrano

Estudiante

Aqui el contenido del openapi.yaml

Sugiero que completes el index.js con un IDE que integre la IA como VSCode o Windsurf.

openapi: 3.1.1
info:
  title: API First
  version: 1.0.0
  description: API First
servers:
  - url: http://localhost:3000
components:
  schemas:
    HelloResponse:
      type: object
    Product:
      type: object
      required:
        - name
        - price
        - category
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 50
        description:
          type: string
          maxLength: 400
        price:
          type: number
          minimum: 0
          multipleOf: 0.01
        category:
          type: string
          enum: [electronics, books, clothes, food]
        tags:
          type: array
          items:
            type: string
          minItems: 1
        inStock:
          type: boolean
        specifications:
          type: object
          additionalProperties:
            type: string
        ratings:
          type: array
          items:
            type: object
            required:
              - score
              - comment
            properties:
              score:
                type: integer
                minimum: 1
                maximum: 5
              comment:
                type: string
                maxLength: 200

paths:
  /hello:
    get:
      summary: Hello World  
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelloResponse'
  /users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - age
                - email
              properties:
                name:
                  type: string
                  minLength: 2
                age:
                  type: integer
                  minimum: 18
                email:
                  type: string
                  format: email
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  age:
                    type: integer
                  email:
                    type: string
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string  
    post:
      summary: update user's name by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - age
                - email
              properties:
                name:
                  type: string
                  minLength: 2    
                age:
                  type: integer
                  minimum: 18
                email:
                  type: string
                  format: email
      responses:    
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  age:
                    type: integer
                  email:
                    type: string
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /products:
    post:
      summary: Crear un nuevo producto
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '201':
          description: Producto creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Datos invalidos
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
    get:
      summary: Obtener una lista de productos
      responses:
        '200':
          description: Lista de productos obtenida exitosamente
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
  /products/{id}:
    get:
      summary: Obtener un producto por ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Producto encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Producto no encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
    put:
      summary: Actualizar un producto por ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Producto actualizado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Producto no encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
    delete:
      summary: Eliminar un producto por ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Producto eliminado exitosamente
        '404':
          description: Producto no encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

William Serrano

Estudiante

Aquí el index.js igual al del profesor

const express = require("express");
const swaggerUi = require("swagger-ui-express");
const YAML = require("yamljs");
const OpenApiValidator = require("express-openapi-validator");

const app = express();
const port = 3000;

const swaggerDocument = YAML.load("./openapi.yaml");
app.use("/docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.use(express.json());

app.use(
  OpenApiValidator.middleware({
    apiSpec: "./openapi.yaml",
    validateRequests: true,
    validateResponses: true,
    ignorePaths: /.*\/docs.*/, // Ignorar rutas de documentación
  }),
);

app.use((err, req, res, next) => {
  res.status(err.status || 500).json({
    message: err.message,
    errors: err.errors,
  });
});

app.get('/hello', (req, res) => {
  res.json({ message: 'hello world' });
});

app.post('/user', (req, res) => {
  const { name, age, email } = req.body;
  const newUser = { 
    id: Date.now().toString(), 
    name, 
    age, 
    email 
  };
  res.status(201).json(newUser);
});

// Simulamos una base de datos simple con un array
const users = [{
    id: 1,
    name: "Juan Perez",
    age: 30,
    email: "juan@example.com",
},{
    id: 2,
    name: "María García",
    age: 25,
    email: "maria@example.com",
},{
    id: 3,
    name: "Carlos López",
    age: 35,
    email: "carlos@example.com",
}];

app.get('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const user = users.find(u => u.id === userId);

  if (!user) {
    return res.status(404).json({ message: "Usuario no encontrado" });
  } 
  
  res.json({
    id: user.id,
    name: user.name
  });
});

app.post('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const { name, age, email } = req.body;

  const userIndex = users.findIndex(u => u.id === userId);

  if (userIndex === -1) {
    return res.status(404).json({ message: "Usuario no encontrado" });
  }

  const UpdatedUser = { 
    id: userId, 
    name, 
    age, 
    email 
  };

  users[userIndex] = UpdatedUser;

  res.json(UpdatedUser);
});

// Simulamos una base de datos simple para producto
const products = [{
  id: "1",
  name: "Laptop HP",
  description: "Laptop HP de ultima generación",
  price: 1299.99,
  category: "electronics",
  tags: ["laptop", "computing"],
  inStock: true,
  specifications: {
    'RAM': '16GB',
    'Storage': '512GB SSD',
  },
  ratings: [{
    score: 5,
    comment: "Excelente rendimiento"
  }] 
}, {
  id: "2",
  name: "Libro Clean Code",
  description: "Libro sobre principios de programación limpia",
  price: 29.99,
  category: "books",
  tags: ["programing", "software"],
  inStock: true,
  specifications: {
    'Pages': "464",
    'Language': 'English',
  },
  ratings: [{ 
    score: 4, 
    comment: "Buena calidad" 
  }],
}];

// Endpoint para productos
app.post("/products", (req, res) => {
  const newProduct = {
    id: Date.now().toString(),
    ...req.body
  };
  products.push(newProduct);
  res.status(201).json(newProduct);
});

app.get("/products", (req, res) => {
  res.json(products);
});

app.get("/products/:id", (req, res) => {
  const product = products.find(p => p.id === req.params.id);

  if (!product) {
    return res.status(404).json({ message: "Producto no encontrado" });
  }

  res.json(product);
});

app.put("/products/:id", (req, res) => {
  const productIndex = products.findIndex(p => p.id === req.params.id);

  if (productIndex === -1) {
    return res.status(404).json({ message: "Producto no encontrado" });
  }

  const updatedProduct = {
    id: req.params.id,
    ...req.body
  };

  products[productIndex] = updatedProduct;
  res.json(updatedProduct);
});

app.delete("/products/:id", (req, res) => {
  const productIndex = products.findIndex(p => p.id === req.params.id);

  if (productIndex === -1) {
    return res.status(404).json({ message: "Producto no encontrado" });
  }

  products.splice(productIndex, 1);
  res.status(204).send();
});

app.listen(port, () => {
  console.log(`Servidor funcionando en puerto ${port}`);
});

Introducción y Fundamentos de API First

API First con OpenAPI antes de programar

Especificación OpenAPI para documentar APIs RESTful

Configuración inicial de proyecto ExpressJS con especificación OpenAPI

Construcción de API con Express y documentación Swagger

Herramientas y Validación de APIs

Validación automática con Express OpenAPI Validator

Validación automática con OpenAPI en Express

Múltiples respuestas HTTP en OpenAPI

Cómo la IA genera endpoints desde OpenAPI

Esquemas reutilizables de productos en OpenAPI

Endpoints de productos con esquemas reutilizables