Qué es una API REST

Casi toda app que usas habla con un servidor mediante una API. La app del clima pide el pronóstico, el panel de un bot lista servidores, la web de una tienda crea un pedido. En la mayoría de los casos, esa conversación sigue el estilo REST.

REST no es un protocolo ni una biblioteca. Es un conjunto de reglas de diseño, descrito por Roy Fielding en su tesis doctoral del año 2000 y aplicado hoy sobre HTTP. Entender esas reglas ayuda tanto a consumir APIs como a diseñar la tuya.

¿Cómo funciona una API REST?#

El cliente (una app, un navegador, un bot) envía una petición HTTP a una URL. El servidor la procesa y devuelve una respuesta con un código de estado y, normalmente, un cuerpo en JSON.

curl -i https://api.ejemplo.com/libros/1

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1, "titulo": "Don Quijote"}

La petición tiene tres partes que importan: el método (qué hacer), la URL (sobre qué recurso) y, a veces, un cuerpo con datos. La respuesta devuelve el estado (si funcionó) y la representación del recurso, generalmente JSON.

¿Cuáles son los principios de REST?#

Fielding describe REST como un conjunto de restricciones arquitectónicas:

• Cliente y servidor separados: la interfaz de usuario y el almacenamiento de datos evolucionan de forma independiente.
• Sin estado (stateless): cada petición lleva todo lo que el servidor necesita, como el token de autenticación. El servidor no guarda sesión entre llamadas.
• Caché: la respuesta indica si puede reutilizarse, lo que reduce el tráfico.
• Interfaz uniforme: recursos identificados por URL y manipulados mediante representaciones, con mensajes autodescriptivos y enlaces entre recursos (hipermedia).
• Sistema en capas: entre el cliente y el servidor puede haber proxies, CDN y balanceadores sin que el cliente lo note.
• Código bajo demanda (opcional): el servidor puede enviar código ejecutable al cliente.

En la práctica, la mayoría de las APIs "REST" implementan bien las primeras ideas e ignoran la hipermedia. Funciona, y es lo que encontrarás a diario.

¿Qué método HTTP usar para cada acción?#

Los métodos se definen en la RFC 9110. Dos conceptos ayudan a elegir: un método es seguro cuando no cambia nada en el servidor, e idempotente cuando repetir la llamada tiene el mismo efecto que hacerla una vez.

La idempotencia importa cuando la red falla. Si un DELETE /libros/1 agota el tiempo de espera, puedes repetirlo sin miedo. Repetir un POST puede crear dos registros.

¿Cómo diseñar URLs y códigos de estado?#

Las URLs nombran cosas, no acciones. El método ya indica la acción.

• Bien: GET /libros, GET /libros/1, POST /libros, DELETE /libros/1.
• Mal: GET /buscarLibro?id=1, POST /borrarLibro.

Usa el plural para las colecciones y anida solo cuando la relación sea clara, como /autores/3/libros. Los códigos de estado más usados:

Devolver 200 con {"error": true} en el cuerpo es un error común: rompe clientes, cachés y herramientas de monitoreo que solo miran el estado.

¿Cómo es un ejemplo de API REST en Node.js?#

Con una versión reciente de Node.js, instala Express 5 y crea server.mjs:

npm install express@5

import express from "express";

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

const libros = [{ id: 1, titulo: "Don Quijote" }];
let siguienteId = 2;

app.get("/libros", (_req, res) => res.json(libros));

app.get("/libros/:id", (req, res) => {
  const libro = libros.find((l) => l.id === Number(req.params.id));
  if (!libro) return res.status(404).json({ error: "Libro no encontrado" });
  res.json(libro);
});

app.post("/libros", (req, res) => {
  const { titulo } = req.body ?? {};
  if (typeof titulo !== "string" || titulo === "") {
    return res.status(400).json({ error: "titulo es obligatorio" });
  }
  const libro = { id: siguienteId++, titulo };
  libros.push(libro);
  res.status(201).location(`/libros/${libro.id}`).json(libro);
});

app.delete("/libros/:id", (req, res) => {
  const i = libros.findIndex((l) => l.id === Number(req.params.id));
  if (i === -1) return res.status(404).json({ error: "Libro no encontrado" });
  libros.splice(i, 1);
  res.sendStatus(204);
});

app.listen(process.env.PORT ?? 3000);

Ejecútalo con node server.mjs y prueba:

curl -i localhost:3000/libros/1
curl -i -X POST localhost:3000/libros -H "Content-Type: application/json" -d '{"titulo":"La Celestina"}'
curl -i -X DELETE localhost:3000/libros/2
curl -i localhost:3000/libros/99

Deberías ver 200, 201, 204 y 404. Los datos quedan en memoria y se pierden al reiniciar; una API real necesita una base de datos. Antes de publicar, repasa la checklist de API en producción.

¿Cuándo una API REST no es la mejor opción?#

REST funciona bien para operaciones de petición y respuesta sobre recursos. En otros escenarios se queda corto:

• Tiempo real: chat, juegos y cotizaciones necesitan una conexión abierta. Mira qué es un WebSocket.
• Pantallas que necesitan datos de varios recursos: encadenar muchas llamadas vuelve lenta la pantalla, y GraphQL permite pedirlo todo de una vez.
• Acciones que no son CRUD: "aprobar pedido" no siempre encaja en un recurso. Un POST /pedidos/5/aprobacion suele resolverlo.

No hay un ganador universal. REST es la opción más común porque es simple, usa lo que HTTP ya ofrece y cualquier lenguaje puede consumirla.

¿Qué diferencia hay entre REST, RESTful y otros términos?#

• RESTful: una API que sigue el estilo REST.
• API HTTP: término más neutro, usado cuando la API usa HTTP pero no cumple todas las restricciones.
• RPC: llamadas a funciones remotas, como POST /crearPedido. Acciones en lugar de recursos.
• Webhook: el camino inverso, en que el servidor llama a una URL tuya cuando algo ocurre.

Para ponerla en línea, mira cómo alojar una API.

Cómo hacerlo en Square Cloud#

Una API REST es una aplicación que escucha en un puerto y responde peticiones HTTP, así que el ejemplo anterior corre como cualquier app Node.js. Haces el deploy subiendo un ZIP en el panel, con la CLI, desde GitHub o con la extensión de VS Code, y cada aplicación web recibe un subdominio *.squareweb.app con HTTPS.

El archivo de configuración squarecloud.app es opcional: el panel lo genera en el deploy, con runtime, memoria y archivo principal. Una aplicación web necesita al menos 512 MB de la RAM de tu plan. Hay runtimes para Node.js, Python, Go, Java, PHP y más. Todos los planes incluyen tráfico sin cobro por ancho de banda ni por petición (política de uso justo), protección DDoS y WAF. Si tu API usa base de datos, el alojamiento de PostgreSQL, MySQL, MongoDB y Redis empieza en el plan Standard.

Square Cloud tiene su propia API REST (api.squarecloud.app/v2), con SDK oficiales en JavaScript/TypeScript, Python y Go. Para publicar la tuya, mira la página de alojamiento de APIs.