Cómo Funciona una API REST

Audiencia

Esta guía es para cualquier persona que necesite entender cómo funcionan las APIs REST:

• Desarrolladores backend construyendo APIs para aplicaciones web y móviles
• Desarrolladores frontend consumiendo APIs para construir interfaces de usuario
• Product managers definiendo funcionalidades que dependen de integración de APIs
• Profesionales de seguridad revisando arquitecturas e implementaciones de APIs
• Arquitectos técnicos diseñando sistemas que se comunican por HTTP
• Cualquier persona curiosa sobre cómo las aplicaciones modernas se comunican entre sí

No se requiere experiencia previa con APIs—empezaremos desde los fundamentos.

Objetivo

Después de leer esta guía, entenderás:

• Qué problema resuelven las APIs y por qué existen
• Cómo HTTP habilita la comunicación entre sistemas
• Qué significa REST y por qué se convirtió en el estilo de API dominante
• Cómo funcionan juntos los recursos, métodos y códigos de estado
• Qué hace que una API sea “RESTful” (y qué no)
• Patrones comunes y anti-patrones en diseño de APIs REST

No serás todavía un arquitecto de APIs, pero tendrás un modelo mental sólido de cómo funcionan las APIs REST y por qué están diseñadas de la forma en que están.

1. Qué Problema Resuelven las APIs

Imagina que estás construyendo una app móvil que muestra el saldo de la cuenta bancaria de un usuario. Tu app se ejecuta en un teléfono. La base de datos del banco se ejecuta en un servidor a miles de kilómetros de distancia. Estos dos sistemas no pueden compartir memoria—son máquinas físicamente separadas.

El problema fundamental: ¿Cómo se comunican estos sistemas de forma confiable, segura y consistente?

Entra en escena la API (Application Programming Interface - Interfaz de Programación de Aplicaciones). Una API es un contrato que define cómo dos sistemas intercambian información. Es como el menú de un restaurante: tú (el cliente) ves lo que puedes pedir (operaciones disponibles), y la cocina (el servidor) sabe qué preparar cuando haces un pedido (solicitud).

graph LR
    A[Cliente
Tu app móvil] -->|Solicitud| B[API
El contrato]
    B -->|Solicitud| C[Servidor
Base de datos]

Las APIs resuelven tres problemas críticos:

1. Separación de responsabilidades: La app móvil no necesita saber cómo el banco almacena los datos. Solo necesita saber cómo pedirlos.
2. Contratos estables: Mientras la API no cambie, ambos sistemas pueden evolucionar independientemente.
3. Comunicación entre fronteras: Diferentes equipos, organizaciones o incluso empresas pueden integrar sus sistemas a través de APIs bien definidas.

Términos clave introducidos:

• Sistema: Cualquier aplicación o servicio de software (app móvil, servidor web, base de datos)
• Cliente: El sistema que hace solicitudes (tu app)
• Servidor: El sistema que responde a solicitudes (la API del banco)
• Contrato: Las reglas acordadas para la comunicación (qué solicitudes son válidas, qué respuestas esperar)

2. Qué es una API (Sin Jerga Innecesaria)

Aclaremos algunas confusiones.

Una API no es solo una URL como https://api.banco.com/cuentas. Eso es un endpoint—una dirección específica dentro de una API.

Una API es toda la interfaz que un servidor expone. Piénsalo como el menú completo de un restaurante, no solo un plato. La API incluye:

• Todas las operaciones disponibles (obtener saldo de cuenta, transferir dinero, ver transacciones)
• Cómo solicitar cada operación (qué datos enviar)
• Qué respuestas esperar (éxito, errores, formatos de datos)

API vs. Aplicación Web: ¿Cuál es la Diferencia?

Tanto las aplicaciones web como las APIs usan HTTP y responden a solicitudes. Entonces, ¿cuál es la diferencia?

Ejemplo: Cuando visitas https://banco.com en tu navegador, obtienes una página web con botones y formularios. Cuando tu app móvil solicita https://api.banco.com/cuentas, obtiene datos estructurados:

{
  "numeroCuenta": "123456789",
  "saldo": 5432.10,
  "moneda": "USD"
}

Qué Significa “Consumir una API”

Cuando los desarrolladores dicen que están “consumiendo una API,” significa que su código está haciendo solicitudes HTTP a esa API y procesando las respuestas. El cliente (consumidor) depende de que el contrato de la API permanezca estable.

Analogía reveladora: Si un restaurante de repente cambia “Hamburguesa” para significar “Ensalada” sin aviso, los clientes se confundirán. De forma similar, si una API cambia saldo de número a cadena de texto, todas las apps cliente se rompen.

3. Por Qué HTTP es el Lenguaje Común

Podrías inventar tu propio protocolo para comunicación cliente-servidor, pero ¿por qué lo harías? HTTP (Hypertext Transfer Protocol - Protocolo de Transferencia de Hipertexto) ya es universal, probado en batalla y entendido por todos los lenguajes de programación.

Qué es Realmente HTTP

HTTP es un protocolo solicitud-respuesta. El cliente envía una solicitud, y el servidor devuelve una respuesta. Eso es todo.

sequenceDiagram
    participant C as Cliente
    participant S as Servidor
    C->>S: Solicitud HTTP
    Note over C,S: Método, Ruta, Cabeceras, Cuerpo
    S->>C: Respuesta HTTP
    Note over C,S: Código de Estado, Cabeceras, Cuerpo

Cada solicitud HTTP incluye:

1. Método: Qué acción realizar (GET, POST, PUT, DELETE, etc.)
2. Ruta: Sobre qué recurso actuar (/usuarios/123)
3. Cabeceras: Metadatos sobre la solicitud (autenticación, tipo de contenido)
4. Cuerpo (opcional): Datos que se están enviando (ej., detalles de usuario a crear)

Cada respuesta HTTP incluye:

1. Código de estado: ¿Funcionó? (200 OK, 404 No Encontrado, 500 Error, etc.)
2. Cabeceras: Metadatos sobre la respuesta
3. Cuerpo (opcional): Datos que se están devolviendo

Qué Significa Sin Estado (Stateless)

HTTP es stateless (sin estado). El servidor no recuerda solicitudes anteriores. Cada solicitud debe contener todo lo que el servidor necesita para entenderla.

Por qué esto importa: Si haces una solicitud para obtener el perfil del usuario 123, y luego inmediatamente solicitas las transacciones del usuario 123, el servidor no recuerda que acabas de preguntar sobre el usuario 123. Cada solicitud es independiente.

Cómo los clientes manejan esto: Envían tokens de autenticación (como JWT) con cada solicitud, para que el servidor sepa quién está preguntando sin recordar interacciones previas.

GET /usuarios/123/transacciones [HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/)
Host: api.banco.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cada solicitud lleva su propio contexto.

4. Qué Significa REST (No Como Religión)

REST significa Representational State Transfer (Transferencia de Estado Representacional). No es un protocolo o un estándar—es un estilo arquitectónico definido por Roy Fielding en su tesis doctoral del año 2000.

REST como Estilo, No como Ley

Piensa en REST como estilos arquitectónicos en edificios. “Victoriano,” “Moderno,” o “Brutalista” describen principios de diseño, pero dos casas victorianas pueden verse muy diferentes. REST es similar: es un conjunto de principios para diseñar aplicaciones en red.

Principios core de REST:

1. Separación Cliente-Servidor: Clientes y servidores son independientes. Solo se comunican a través de la API.
2. Sin Estado: Cada solicitud contiene toda la información necesaria. El servidor no almacena el estado del cliente entre solicitudes.
3. Cacheable: Las respuestas deben indicar si pueden ser cacheadas para mejorar el rendimiento.
4. Interfaz Uniforme: Los recursos se identifican por URLs, y tú interactúas con ellos usando métodos HTTP estándar.
5. Sistema en Capas: El cliente no puede saber si está conectado directamente al servidor o a través de intermediarios (balanceadores de carga, proxies).

Qué Aporta REST

Las APIs REST aprovechan la semántica existente de HTTP en lugar de inventar nuevas. Beneficios:

• Predictibilidad: Si has usado una API REST, entiendes los patrones usados por otras.
• Tooling: Los debuggers HTTP, proxies, cachés y CDNs funcionan out of the box.
• Escalabilidad: La ausencia de estado y la capacidad de cacheo hacen más fácil escalar servidores horizontalmente.

Qué Sucede Cuando No lo Sigues

No seguir REST no es un pecado—es un tradeoff. Pero esto es lo que pierdes:

• Confusión: Una API que usa POST para todo es más difícil de entender y depurar.
• Optimizaciones perdidas: Los navegadores y proxies cachean solicitudes GET por defecto. Si usas POST para lecturas, pierdes cacheo gratuito.
• Romper la semántica HTTP: Las herramientas asumen que GET es seguro (sin efectos secundarios). Si tu GET request elimina datos, los crawlers automatizados podrían destrozar tu sistema.

REST no es dogma, pero sus principios se alinean con cómo HTTP fue diseñado para funcionar.

5. Recursos, No Acciones

En REST, no piensas en términos de acciones (verbos). Piensas en términos de recursos (sustantivos).

Qué es un Recurso

Un resource (recurso) es cualquier entidad que tu API expone: un usuario, una cuenta, una transacción, un documento, una configuración. Cada recurso tiene un identificador único (URL).

Ejemplos:

• /usuarios/123 → Usuario con ID 123
• /cuentas/456 → Cuenta con ID 456
• /cuentas/456/transacciones → Colección de transacciones para la cuenta 456

Insight clave: Los recursos pueden ser elementos individuales (singular) o colecciones (plural).

graph TD
    A["/cuentas"] -->|Colección| B[Todas las cuentas]
    C["/cuentas/456"] -->|Individual| D[Cuenta específica]
    E["/cuentas/456/transacciones"] -->|Sub-colección| F[Transacciones cuenta 456]

Por Qué /usuarios/123 No es un Verbo

Mal diseño de API:

POST /crearUsuario
POST /obtenerUsuario
POST /eliminarUsuario

Esto es RPC (Remote Procedure Call - Llamada a Procedimiento Remoto) sobre HTTP. Estás exponiendo acciones como endpoints.

Buen diseño REST:

POST /usuarios          → Crear usuario
GET /usuarios/123       → Obtener usuario
DELETE /usuarios/123    → Eliminar usuario

El recurso es /usuarios o /usuarios/123. La acción es el método HTTP (POST, GET, DELETE). Esta separación mantiene las URLs limpias y la semántica clara.

Por Qué POST /login Ya es una Concesión

Hablando estrictamente, /login no es un recurso—es una acción. En REST puro, lo modelarías como:

POST /sesiones       → Crear una nueva sesión (login)
DELETE /sesiones/xyz → Destruir sesión (logout)

Pero la mayoría de las APIs usan POST /login porque es intuitivo. Esto está bien. REST es una guía, no una camisa de fuerza. La clave es la consistencia: si rompes los principios REST, hazlo intencionalmente y documéntalo claramente.

6. Métodos HTTP y Semántica

Los HTTP methods (métodos HTTP) definen la acción que quieres realizar sobre un recurso. Los métodos más comunes son GET, POST, PUT, PATCH y DELETE.

Los Cinco Grandes

Seguro vs. Idempotente

Dos propiedades críticas definen cómo se comportan los métodos:

Métodos seguros (safe-methods): No modifican recursos. Puedes llamarlos repetidamente sin efectos secundarios.

• ✅ GET, HEAD, OPTIONS
• ❌ POST, PUT, DELETE

Métodos idempotentes (idempotency): Llamarlos múltiples veces tiene el mismo efecto que llamarlos una vez.

• ✅ GET, PUT, DELETE
• ❌ POST

graph TD
    A[Métodos HTTP] --> B[Seguros]
    A --> C[No Seguros]
    B --> D[GET, HEAD, OPTIONS]
    C --> E[Idempotentes]
    C --> F[No Idempotentes]
    E --> G[PUT, DELETE]
    F --> H[POST]

Por qué esto importa:

• Los métodos seguros pueden ser cacheados, pre-cargados y reintentados sin riesgo.
• Los métodos idempotentes pueden ser reintentados de forma segura si la red falla (¿funcionó? Envíalo de nuevo).
• Los métodos no idempotentes (POST) son peligrosos de reintentar automáticamente.

Ejemplo: Si haces clic en “Enviar Pedido” y la red se desconecta, ¿la app debería reintentar?

• Si es POST /pedidos → No, podrías crear dos pedidos.
• Si es PUT /pedidos/123 → Sí, reintentar no creará duplicados.

Por Qué Usar Mal los Métodos Rompe a los Clientes

Si usas GET para eliminar recursos:

GET /usuarios/123?accion=eliminar

Has roto la semántica HTTP. Consecuencias:

1. Cacheo: Los proxies cachean solicitudes GET. Una respuesta cacheada significa que la eliminación nunca ocurre.
2. Precarga del navegador: Los navegadores precargan enlaces GET para acelerar la navegación. El navegador de tu usuario podría eliminar datos solo al pasar el mouse sobre un enlace.
3. Crawlers: Los bots de motores de búsqueda siguen enlaces GET. Eliminarán todos tus datos.

Usa el método correcto para el trabajo correcto.

7. Códigos de Estado: El Lenguaje de los Errores

Los HTTP status codes (códigos de estado HTTP) le dicen al cliente qué sucedió. Están agrupados por categoría:

Las Cinco Familias

Por Qué No Todo es 200

Devolver 200 OK para errores es un anti-patrón:

HTTP/1.1 200 OK

{
  "exito": false,
  "error": "Usuario no encontrado"
}

Problemas:

• Los proxies HTTP ven 200 y piensan que todo está bien.
• Las herramientas de monitoreo no pueden detectar errores.
• Los clientes tienen que parsear el cuerpo para saber si funcionó.

Mejor enfoque:

HTTP/1.1 404 Not Found

{
  "error": "Usuario no encontrado",
  "codigo": "USUARIO_NO_ENCONTRADO"
}

Ahora el código de estado lleva significado semántico. Las herramientas pueden detectar errores sin parsear JSON.

Diferencia Entre 401 y 403

Estos dos a menudo se confunden:

• 401 Unauthorized: No te has autenticado. “No sé quién eres. Por favor inicia sesión.”
• 403 Forbidden: Estás autenticado, pero no tienes permiso. “Sé quién eres, pero no puedes acceder a esto.”

flowchart TD
    A[Solicitud] --> B{¿Autenticado?}
    B -->|No| C[401 Unauthorized]
    B -->|Sí| D{¿Autorizado?}
    D -->|No| E[403 Forbidden]
    D -->|Sí| F[200 OK]

Ejemplo:

• Acceder a /usuarios/123 sin token → 401
• Acceder a /admin/usuarios como usuario regular → 403

Error del Cliente vs. Error del Servidor

Los errores 4xx significan que el cliente envió una solicitud incorrecta. Es culpa del cliente:

• 400 Bad Request: JSON malformado, campos requeridos faltantes
• 404 Not Found: El recurso no existe
• 429 Too Many Requests: Límite de tasa excedido

Los errores 5xx significan que el servidor falló al procesar una solicitud válida. Es culpa del servidor:

• 500 Internal Server Error: Excepción no manejada
• 502 Bad Gateway: El servidor upstream falló
• 503 Service Unavailable: El servidor está sobrecargado o caído

Por qué la distinción importa: Los clientes deberían reintentar errores 5xx (el servidor podría recuperarse). No deberían reintentar errores 4xx (la solicitud está rota y no funcionará incluso si se reintenta).

8. Datos: Cabeceras, Cuerpo y Formatos

Las solicitudes y respuestas HTTP tienen dos lugares para poner datos: cabeceras y cuerpo.

Qué Va en las Cabeceras

Las cabeceras contienen metadatos sobre la solicitud o respuesta—información sobre los datos, no los datos en sí.

Cabeceras de solicitud comunes:

Authorization: Bearer eyJhbGci...      # Quién eres
Content-Type: application/json        # Formato del cuerpo que estás enviando
Accept: application/json               # Formato que quieres de vuelta
User-Agent: MiApp/1.0                  # Información del cliente

Cabeceras de respuesta comunes:

Content-Type: application/json        # Formato del cuerpo
Cache-Control: max-age=3600            # Cuánto tiempo cachear esto
X-Rate-Limit-Remaining: 99             # Custom: info de límite de tasa de la API

Qué Va en el Cuerpo

El cuerpo contiene los datos reales:

Cuerpo de solicitud (POST/PUT/PATCH):

{
  "nombre": "Alicia",
  "email": "[email protected]",
  "edad": 30
}

Cuerpo de respuesta (GET):

{
  "id": 123,
  "nombre": "Alicia",
  "email": "[email protected]",
  "creadoEn": "2026-01-09T10:00:00Z"
}

JSON como Formato Dominante

Aunque HTTP soporta cualquier formato (XML, CSV, HTML), JSON (JavaScript Object Notation) es el estándar de facto para APIs REST.

Por qué JSON ganó:

• Legible para humanos
• Soportado nativamente por JavaScript (navegadores)
• Compacto (más pequeño que XML)
• Fácil de parsear en cualquier lenguaje

Ejemplo de respuesta JSON:

{
  "usuario": {
    "id": 123,
    "nombre": "Alicia",
    "cuentas": [
      {
        "id": 456,
        "saldo": 5432.10,
        "moneda": "USD"
      },
      {
        "id": 789,
        "saldo": 1200.00,
        "moneda": "EUR"
      }
    ]
  }
}

Qué es la Negociación de Contenido (Brevemente)

La negociación de contenido permite a los clientes solicitar diferentes formatos usando la cabecera Accept:

GET /usuarios/123
Accept: application/json        → El servidor devuelve JSON

GET /usuarios/123
Accept: application/xml         → El servidor devuelve XML

La mayoría de las APIs modernas solo soportan JSON e ignoran la cabecera Accept, pero el principio es parte de la interfaz uniforme de REST.

9. Qué NO es una API REST

Aclaremos malentendidos mostrando qué no es REST.

RPC sobre HTTP

Una API que expone acciones como endpoints:

POST /crearUsuario
POST /eliminarUsuario
POST /calcularInteres
POST /enviarEmail

Esto es RPC (Remote Procedure Call) sobre HTTP, no REST. No está mal, pero no es REST:

• Las URLs son verbos, no sustantivos
• Todo usa POST
• Pierdes la semántica incorporada de HTTP (cacheo, idempotencia)

Cuándo RPC tiene sentido: Microservicios internos, acciones que no se mapean a recursos (ej., /calcular-ruta).

APIs que Cambian Sin Aviso

Una “API REST” que devuelve diferentes estructuras de datos para el mismo endpoint:

Lunes:

{
  "saldo": 1234.56
}

Martes (cambio que rompe):

{
  "saldoCuenta": "1234.56 USD"
}

Cambiar saldo a saldoCuenta (o número a cadena) rompe todos los clientes. Las APIs REST deben ser estables y versionadas. Los cambios deben ser retrocompatibles o introducidos en una nueva versión de la API.

APIs que Devuelven HTML o Errores Inconsistentes

Si tu API devuelve HTML cuando hay un error:

HTTP/1.1 500 Internal Server Error
Content-Type: text/html

<html>
  <body>
    <h1>¡Ups! Algo salió mal.</h1>
  </body>
</html>

Tu cliente (esperando JSON) fallará intentando parsear HTML. La consistencia importa. Si tu API devuelve JSON, siempre devuelve JSON—incluso para errores.

GraphQL y gRPC: Paradigmas Diferentes

GraphQL y gRPC no son REST:

• GraphQL: Un solo endpoint (/graphql), los clientes consultan exactamente lo que necesitan.
• gRPC: Protocolo binario usando Protobuf, diseñado para alto rendimiento entre microservicios.

Estas son alternativas válidas a REST, no “mejores” o “peores”—solo herramientas diferentes para casos de uso diferentes.

10. Qué Viene Después

Ahora entiendes los fundamentos de cómo funcionan las APIs REST. Aquí está cómo profundizar más:

Guías Futuras (Próximamente)

1. Mejores Prácticas de Diseño de APIs: Cómo diseñar APIs REST intuitivas y escalables
2. Fundamentos de Seguridad de APIs: Autenticación, autorización y vulnerabilidades comunes
3. Estrategias de Versionado de APIs: Cómo evolucionar APIs sin romper clientes
4. Optimización de Rendimiento de APIs: Cacheo, paginación, límites de tasa y compresión
5. OpenAPI y Documentación: Cómo documentar APIs con OpenAPI 3.x

Términos del Vocabulario Relacionados

Profundiza tu comprensión explorando estos términos:

• REST - Estilo arquitectónico para aplicaciones en red
• RESTful API - APIs que siguen principios REST
• HTTP - El protocolo que impulsa las APIs REST
• Resource - El concepto fundamental en REST
• Client-Server - Separación de responsabilidades en sistemas distribuidos
• Stateless - Por qué las APIs REST no recuerdan solicitudes previas
• HTTP Methods - GET, POST, PUT, DELETE, y más
• Idempotency - Por qué algunos métodos son seguros de reintentar
• Safe Methods - Métodos que no modifican recursos
• HTTP Status Codes - El lenguaje del éxito y los errores

Herramientas para Explorar

• Postman o Insomnia: Prueba APIs REST interactivamente
• curl: Herramienta de línea de comandos para hacer solicitudes HTTP
• Browser DevTools: Pestaña de red para inspeccionar llamadas a APIs desde apps web
• OpenAPI (Swagger): Define y documenta tus APIs

¡Felicitaciones! Has construido un modelo mental de cómo funcionan las APIs REST. El siguiente paso es la práctica hands-on: explora APIs públicas, construye la tuya propia y ve estos principios en acción.