Definición:
Una API REST es una interfaz de programación de aplicaciones diseñada según los principios del estilo arquitectónico REST, normalmente sobre HTTP. Expone recursos mediante identificadores y permite que un cliente consulte o modifique sus representaciones a través de operaciones con una semántica definida.
REST no es un protocolo ni obliga a utilizar JSON. Es un estilo arquitectónico con restricciones concretas para sistemas distribuidos. Una API puede usar HTTP y devolver JSON sin cumplir todas esas restricciones; en ese caso puede ser una API HTTP, pero no necesariamente una implementación REST completa.
Índice de contenidos
Para qué sirve una API REST
Una API REST permite que aplicaciones distintas intercambien información mediante una interfaz acordada. Un sitio web, una aplicación móvil o un sistema interno pueden solicitar datos y ejecutar operaciones sin conocer cómo están implementados el almacenamiento o la lógica del servidor.
Este enfoque puede emplearse para conectar una interfaz con su backend, integrar plataformas, publicar datos controlados o coordinar servicios. La API define qué recursos y operaciones están disponibles, mientras que cada consumidor decide cómo incorporarlos a su proceso.
La separación entre cliente y servidor facilita su evolución independiente, pero no elimina el trabajo de diseño. La compatibilidad real depende de contratos estables, documentación, tratamiento de errores y gestión de cambios. REST tampoco garantiza por sí solo rapidez, escalabilidad o seguridad.
Cómo funciona una API REST
El cliente envía una petición HTTP a una URL que identifica un recurso. La petición incluye un método, cabeceras y, cuando corresponde, un cuerpo. El servidor procesa la operación y devuelve una respuesta con un código de estado, cabeceras y una representación del recurso.
Las APIs REST suelen utilizar HTTP y aprovechan la semántica de sus métodos:
- GET: Recupera una representación sin solicitar una modificación del recurso.
- POST: Envía datos para que el servidor los procese o cree un recurso subordinado.
- PUT: Crea o sustituye el estado de un recurso en la dirección indicada.
- PATCH: Solicita una modificación parcial del recurso.
- DELETE: Solicita eliminar la asociación o el recurso identificado.
El cuerpo puede usar JSON, XML, texto u otro formato acordado. Las cabeceras `Content-Type` y `Accept` ayudan a describir o negociar la representación. Los códigos 2xx, 4xx y 5xx informan del resultado, pero su significado concreto debe respetar la semántica de HTTP.
Restricciones del estilo REST
El estilo REST fue descrito por Roy Fielding como un conjunto de restricciones arquitectónicas. No son funciones opcionales añadidas a una API, sino propiedades que determinan cómo interactúan sus componentes.
Las restricciones principales son:
- Cliente y servidor: Se separan las responsabilidades de interfaz y almacenamiento o procesamiento.
- Sin estado: Cada petición contiene la información necesaria para entenderla; el servidor no depende de una sesión conversacional previa.
- Respuestas cacheables: Las respuestas indican si pueden reutilizarse para evitar peticiones equivalentes innecesarias.
- Interfaz uniforme: Los recursos se identifican de forma estable y se manipulan mediante representaciones y mensajes autodescriptivos.
- Sistema por capas: El cliente puede comunicarse a través de intermediarios sin necesitar conocer toda la infraestructura.
- Código bajo demanda: De forma opcional, el servidor puede ampliar temporalmente al cliente mediante código ejecutable.
La interfaz uniforme incluye la navegación mediante hipermedia como motor del estado de la aplicación. Muchas APIs denominadas REST no implementan esta parte por completo, por lo que el término RESTful debe entenderse como un grado de conformidad con el estilo, no como sinónimo automático de cualquier API web.
Diseño de recursos y operaciones
Una API REST se organiza alrededor de recursos identificables, como clientes, pedidos o documentos. Las rutas suelen utilizar nombres que representan esos recursos, mientras que el método HTTP expresa la operación. Así se evita codificar acciones incompatibles con la semántica del método dentro de la URL.
El diseño debe considerar estas propiedades:
- Seguridad del método: GET y HEAD se definen como métodos seguros porque no solicitan cambiar el estado del servidor.
- Idempotencia: Repetir PUT o DELETE con la misma intención debería producir el mismo efecto final que ejecutarlos una vez.
- Códigos coherentes: Cada respuesta debe diferenciar resultados correctos, errores del cliente y fallos del servidor.
- Paginación y filtros: Las colecciones grandes necesitan límites y criterios explícitos para evitar respuestas descontroladas.
- Evolución compatible: Los cambios de campos, rutas o comportamientos requieren una estrategia de versión y retirada.
La semántica de HTTP establece el significado de métodos y códigos. Una documentación precisa debe añadir parámetros, esquemas, ejemplos, límites y formatos de error para que el contrato público pueda utilizarse y probarse de forma consistente.
Seguridad y límites de una API REST
REST no proporciona comunicación segura de manera automática. La protección depende de usar HTTPS, autenticar identidades, comprobar permisos, validar entradas y limitar el abuso. La autenticación responde quién realiza la petición; la autorización determina qué recursos y acciones puede utilizar.
Un sistema puede aplicar distintos mecanismos, como claves de API, sesiones, certificados o OAuth, según el contexto. OAuth delega acceso, pero no sustituye el cifrado, la validación ni los controles de autorización sobre cada objeto.
También conviene establecer límites de tamaño y frecuencia, registrar fallos relevantes, evitar exponer datos innecesarios y devolver errores que no revelen información sensible. El almacenamiento en caché debe configurarse con cuidado cuando las respuestas contienen datos privados. Una API REST bien diseñada combina las restricciones arquitectónicas con controles operativos, pruebas y supervisión continua.