API REST y verbos HTTP

1.Qué es una API REST

Una API es la «puerta» que un programa ofrece para que otros programas lo usen. Una API REST hace eso sobre HTTP: en lugar de páginas para leer, ofrece recursos (tareas, usuarios, productos…) que otros programas piden y modifican, casi siempre en formato JSON.

REST se apoya en dos ideas sencillas:

• Cada recurso tiene una dirección propia (una URL): /tareas es la colección y /tareas/7 es una tarea concreta.
• El verbo HTTP indica la acción: leer, crear, reemplazar, modificar o borrar.

A este conjunto de operaciones se le llama CRUD: Create (crear), Read (leer), Update (actualizar) y Delete (borrar). Puedes ver la definición oficial de cada método en MDN.

2.Seguros e idempotentes

Dos propiedades explican por qué cada verbo se usa como se usa:

Por eso un navegador puede repetir un GET sin riesgo (por ejemplo, al recargar), pero te avisa antes de reenviar un POST: podría crear un pedido duplicado.

PUT frente a PATCH

Imagina la tarea { "id": 7, "titulo": "Comprar pan", "hecha": false }:

PUT   /tareas/7   cuerpo: { "titulo": "Comprar pan", "hecha": true }   // hay que enviar TODO
PATCH /tareas/7   cuerpo: { "hecha": true }                           // solo lo que cambia

PUT sustituye el recurso completo (lo que no envíes desaparece); PATCH fusiona los cambios con lo que ya había.

3.Un CRUD completo en memoria

Vamos a construir una API de tareas. Para empezar, guardamos los datos en un array en memoria: es lo más simple, aunque se pierde al reiniciar el servidor (en el proyecto final los guardaremos en un archivo).

import express from "express";

const app = express();
app.use(express.json());

let tareas = [
  { id: 1, titulo: "Aprender Express", hecha: false },
  { id: 2, titulo: "Crear mi primera API", hecha: false },
];
let siguienteId = 3;

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

// LEER una
app.get("/tareas/:id", (req, res) => {
  const tarea = tareas.find((t) => t.id === Number(req.params.id));
  if (!tarea) return res.status(404).json({ error: "Tarea no encontrada" });
  res.json(tarea);
});

// CREAR
app.post("/tareas", (req, res) => {
  const { titulo } = req.body ?? {};
  if (typeof titulo !== "string" || titulo.trim() === "") {
    return res.status(400).json({ error: "El título es obligatorio" });
  }
  const nueva = { id: siguienteId++, titulo: titulo.trim(), hecha: false };
  tareas.push(nueva);
  res.status(201).json(nueva);
});

// REEMPLAZAR
app.put("/tareas/:id", (req, res) => {
  const i = tareas.findIndex((t) => t.id === Number(req.params.id));
  if (i === -1) return res.status(404).json({ error: "Tarea no encontrada" });
  const { titulo, hecha } = req.body ?? {};
  if (typeof titulo !== "string" || typeof hecha !== "boolean") {
    return res.status(400).json({ error: "Se requieren titulo y hecha" });
  }
  tareas[i] = { id: tareas[i].id, titulo, hecha };
  res.json(tareas[i]);
});

// MODIFICAR parcialmente
app.patch("/tareas/:id", (req, res) => {
  const tarea = tareas.find((t) => t.id === Number(req.params.id));
  if (!tarea) return res.status(404).json({ error: "Tarea no encontrada" });
  const { titulo, hecha } = req.body ?? {};
  if (titulo !== undefined) tarea.titulo = titulo;
  if (hecha !== undefined) tarea.hecha = hecha;
  res.json(tarea);
});

// BORRAR
app.delete("/tareas/:id", (req, res) => {
  const i = tareas.findIndex((t) => t.id === Number(req.params.id));
  if (i === -1) return res.status(404).json({ error: "Tarea no encontrada" });
  tareas.splice(i, 1);
  res.sendStatus(204);
});

app.listen(3000, () => console.log("API en http://localhost:3000"));

Fíjate en los patrones que se repiten: buscar el recurso, responder 404 si no existe, validar los datos y responder 400 si están mal, y por último actuar y devolver el código correcto.

4.Probar tu API

Con el servidor en marcha, prueba cada verbo. En macOS, Linux o Git Bash:

curl http://localhost:3000/tareas
curl -X POST http://localhost:3000/tareas -H "Content-Type: application/json" -d '{"titulo":"Probar mi API"}'
curl -X PATCH http://localhost:3000/tareas/1 -H "Content-Type: application/json" -d '{"hecha":true}'
curl -X DELETE http://localhost:3000/tareas/2 -i

[{"id":1,"titulo":"Aprender Express","hecha":false},{"id":2,"titulo":"Crear mi primera API","hecha":false}]
{"id":3,"titulo":"Probar mi API","hecha":false}
{"id":1,"titulo":"Aprender Express","hecha":true}
HTTP/1.1 204 No Content

Si prefieres una interfaz gráfica, extensiones del editor (también en Cursor) como REST Client o Thunder Client permiten escribir y enviar peticiones sin recordar la sintaxis de curl. En PowerShell usa curl.exe (y escapa las comillas del JSON, como viste en la lección 4).

Mientras tanto, practica en el navegador la lógica del CRUD con este editor, que usa solo JavaScript puro:

5.Buenas prácticas de diseño

• URLs en plural y en minúsculas: /tareas, /usuarios/3/pedidos.
• Código de estado correcto: 201 al crear, 204 al borrar, 404 si no existe, 400 si los datos son inválidos.
• Siempre JSON, también en los errores, con un formato constante como { "error": "mensaje" }.
• Filtros y orden con query: GET /tareas?hecha=true en lugar de rutas nuevas.
• Sin lógica en las rutas cuando crezca: pasa a funciones o módulos aparte (lo verás en el proyecto final).
• Versiona la API si va a tener clientes externos: /api/v1/tareas.

app.get("/tareas", (req, res) => {
  let resultado = tareas;
  if (req.query.hecha !== undefined) {
    const hecha = req.query.hecha === "true";
    resultado = resultado.filter((t) => t.hecha === hecha);
  }
  res.json(resultado);
});

6.Errores frecuentes

• Verbos en la URL (/crearTarea): usa POST /tareas.
• Responder 200 a todo: crear es 201, borrar suele ser 204 y lo inexistente 404.
• Comparar ids de distinto tipo: req.params.id es texto; conviértelo con Number antes de comparar con ===.
• Confundir PUT y PATCH: PUT exige el recurso completo.
• No validar el cuerpo: guardas basura y la API falla más tarde.
• Olvidar express.json(): req.body llega sin datos.
• Esperar que los datos persistan: un array en memoria desaparece al reiniciar.

7.Glosario