≡En resumen
- REST no es un protocolo ni una norma: es un estilo de arquitectura con seis restricciones, una de ellas opcional.
- En una API REST todo es un recurso con su URL (/clientes/15) y se opera sobre él con verbos HTTP.
- Cada petición lleva toda la información necesaria; el servidor no recuerda peticiones anteriores (stateless).
- Los códigos de estado HTTP (200, 201, 400, 401, 404, 500) indican el resultado de cada operación.
- Se llama «RESTful» a la API que cumple de verdad estos principios; en la práctica, ambos términos se usan como sinónimos.
01 ¿Qué es una API REST?
El término lo acuñó Roy Fielding, uno de los autores de la especificación HTTP, en su tesis doctoral de 2000 en la Universidad de California en Irvine. Fielding no inventó una tecnología nueva: describió los principios que habían hecho escalar la web y propuso aplicarlos al diseño de software distribuido.
Verás también «API RESTful». En sentido estricto, RESTful es la API que cumple todas las restricciones; en el día a día se usa como sinónimo de API REST.
02 Los 6 principios de la arquitectura REST
1. Cliente-servidor
La interfaz (cliente) y el almacenamiento de datos (servidor) están separados y evolucionan de forma independiente.
2. Sin estado (stateless)
Cada petición contiene toda la información necesaria, incluida la autenticación. El servidor no guarda contexto de la sesión entre peticiones.
3. Cacheable
Las respuestas indican si pueden guardarse en caché y durante cuánto tiempo, para ahorrar peticiones.
4. Interfaz uniforme
Recursos identificados por URI, manipulación mediante representaciones, mensajes autodescriptivos e hipermedia (HATEOAS).
5. Sistema en capas
Entre cliente y servidor puede haber proxies, balanceadores o CDN sin que el cliente lo note.
6. Código bajo demanda (opcional)
El servidor puede enviar código ejecutable al cliente, como scripts. Es la única restricción opcional.
03 Métodos HTTP en una API REST
| Método | Ejemplo | Acción | ¿Idempotente? |
|---|---|---|---|
| GET | GET /clientes/15 | Leer el cliente 15 (o la lista con GET /clientes) | Sí |
| POST | POST /clientes | Crear un cliente nuevo | No |
| PUT | PUT /clientes/15 | Reemplazar el cliente 15 completo | Sí |
| PATCH | PATCH /clientes/15 | Modificar solo algunos campos | No necesariamente |
| DELETE | DELETE /clientes/15 | Eliminar el cliente 15 | Sí |
«Idempotente» significa que repetir la misma petición deja el servidor en el mismo estado que hacerla una vez. Es importante cuando falla la red: reintentar un método GET o un DELETE es seguro, pero reintentar un POST puede crear dos pedidos. Estas reglas están definidas en el RFC 9110, el estándar actual de la semántica de HTTP.
04 Códigos de estado HTTP más usados
| Código | Significado | Cuándo se devuelve |
|---|---|---|
| 200 OK | Petición correcta | Lectura o actualización con éxito |
| 201 Created | Recurso creado | Tras un POST que crea un registro |
| 204 No Content | Correcto, sin cuerpo | Tras un DELETE |
| 400 Bad Request | Petición mal formada | Faltan campos o el formato es incorrecto |
| 401 Unauthorized | Sin autenticación válida | Falta el token o ha caducado |
| 403 Forbidden | Sin permiso | El usuario está identificado pero no puede hacer esa acción |
| 404 Not Found | No existe | El recurso pedido no está |
| 429 Too Many Requests | Demasiadas peticiones | Se ha superado el límite de uso |
| 500 Internal Server Error | Error del servidor | Fallo no previsto en el back end |
Devolver el código correcto evita que el cliente tenga que leer el cuerpo para saber si algo falló. Puedes profundizar en el significado del código 200 OK y del error 404 en nuestro diccionario.
05 Ejemplo de API REST
1. Crear: POST /api/v1/reservas con el cuerpo { "cliente_id": 15, "fecha": "2026-10-12", "personas": 4 }
Respuesta: 201 Created y { "id": 902, "estado": "confirmada" }
2. Consultar: GET /api/v1/reservas/902 → 200 OK con los datos de la reserva.
3. Cambiar el número de personas: PATCH /api/v1/reservas/902 con { "personas": 6 } → 200 OK.
La web del restaurante, su app móvil y el panel del personal usan la misma API, así que una reserva hecha desde cualquier canal aparece al instante en los demás.
06 API REST vs SOAP vs GraphQL
| Aspecto | REST | SOAP | GraphQL |
|---|---|---|---|
| Qué es | Estilo de arquitectura | Protocolo con normas estrictas | Lenguaje de consultas para APIs |
| Formato | Normalmente JSON | XML obligatorio | JSON |
| Endpoints | Uno por recurso | Uno por servicio, con operaciones | Normalmente uno solo |
| Caché HTTP | Nativa | Limitada | Requiere trabajo extra |
| Ventaja principal | Sencillez y escalabilidad | Contratos formales y seguridad a nivel de mensaje | Pides exactamente los datos que necesitas |
| Uso típico | Webs, apps y SaaS | Banca, seguros, sistemas heredados | Apps con pantallas complejas |
07 Autenticación y seguridad en una API REST
Como REST no guarda sesión, cada petición tiene que demostrar quién la hace. Los tres mecanismos más habituales son la clave de API, el token Bearer (a menudo un JWT firmado) y el estándar OAuth 2.0, publicado como RFC 6749 en 2012, que permite a una aplicación actuar en nombre de un usuario sin conocer su contraseña.
Clave de API
Un identificador secreto por aplicación. Sencillo, adecuado para integraciones entre servidores.
Token Bearer o JWT
Se obtiene al iniciar sesión y se envía en la cabecera Authorization. Caduca y puede renovarse.
OAuth 2.0
Flujo estándar para delegar permisos, el que hay detrás de «Iniciar sesión con Google».
CORS y límites de uso
Controlan qué dominios pueden llamar a la API desde el navegador y cuántas peticiones se aceptan por minuto.
08 ¿Para qué sirve una API REST en un proyecto real?
- ✓Servir los datos a una web y a una app móvil desde un único back end.
- ✓Integrar tu tienda online con el ERP, el CRM o la empresa de transporte.
- ✓Ofrecer a clientes o partners acceso a tus datos de forma controlada.
- ✓Separar el front-end del back end para poder rediseñar uno sin rehacer el otro.
- ✓Conectar herramientas de automatización e inteligencia artificial.
Las apps móviles, hechas con tecnologías nativas o multiplataforma como las que comparamos en Flutter vs React Native, casi siempre dependen de una API REST. Diseñarla bien desde el principio es una de las decisiones que más influyen en el coste de mantenimiento, y es parte del trabajo de cualquier empresa de desarrollo de aplicaciones o de un proyecto de desarrollo de aplicaciones web a medida.
Preguntas frecuentes sobre API REST
Representational State Transfer, en español transferencia de estado representacional. Es el estilo de arquitectura que Roy Fielding describió en su tesis de 2000.
Es una forma estándar de que dos programas intercambien datos por Internet: cada dato tiene una dirección web y se lee, crea, modifica o borra con los verbos de HTTP.
API es cualquier interfaz entre programas. Una API REST es un tipo concreto de API web que sigue los principios REST y usa HTTP.
REST es el estilo de arquitectura; RESTful es la API que lo aplica. En la práctica se usan como sinónimos.
PUT reemplaza el recurso completo con los datos enviados; PATCH modifica solo los campos indicados.
No. REST no impone formato, pero JSON es el más usado por ser ligero y fácil de leer para personas y programas. También puede devolver XML, HTML u otros.
Con herramientas como Postman, Insomnia o curl, o con tests automatizados que lanzan peticiones y comprueban los códigos de estado y las respuestas.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗