Definición rápida
Una API REST (Representational State Transfer) es un estilo arquitectónico para diseñar servicios web que permite la comunicación entre sistemas usando el protocolo HTTP, con endpoints que representan recursos y operaciones estándar como GET, POST, PUT y DELETE.
¿Qué es una API REST?
Antes de entender REST, entendamos qué es una API: es una interfaz que permite que dos aplicaciones se comuniquen. REST es el estilo arquitectónico más popular para diseñar esas interfaces en la web.
REST fue definido por Roy Fielding en su tesis doctoral del año 2000. Los principios REST son tan elegantes y simples que se convirtieron en el estándar para prácticamente todas las APIs web modernas —desde Twitter hasta Stripe, desde GitHub hasta Mercado Pago.
La idea central de REST es que los recursos (usuarios, productos, órdenes) se representan como URLs, y los verbos HTTP estándar (GET para leer, POST para crear, PUT para actualizar, DELETE para eliminar) son las operaciones disponibles sobre esos recursos.
¿Cómo funciona una API REST en la práctica?
Un ejemplo concreto. Si tienes una plataforma de e-commerce, tu API REST podría verse así:
GET /products→ Obtener lista de productosGET /products/123→ Obtener producto con ID 123POST /products→ Crear un nuevo productoPUT /products/123→ Actualizar el producto 123DELETE /products/123→ Eliminar el producto 123
Los principios REST incluyen:
- Stateless: Cada request contiene toda la información necesaria. El servidor no mantiene estado entre requests.
- Client-Server: Separación clara entre el cliente (quien hace el request) y el servidor (quien lo procesa).
- Cacheable: Las respuestas pueden ser cacheadas para mejorar el rendimiento.
- Uniform Interface: Uso consistente de URLs, verbos HTTP y códigos de respuesta (200, 201, 404, 500).
La autenticación en REST suele implementarse con OAuth 2.0 o API Keys. Las respuestas son generalmente en formato JSON (JavaScript Object Notation).
Ejemplos reales en LATAM
Mercado Pago (Argentina): La API REST de Mercado Pago es la integración de pagos más usada en LATAM. Miles de desarrolladores en Chile, Argentina, Brasil y México integran pagos usando esta API. Su documentación es uno de los mejores ejemplos de API RESTful bien diseñada en español.
Conekta (México): La API REST de Conekta permite a merchants mexicanos procesar pagos con tarjeta, OXXO y transferencias SPEI. Es el ejemplo más usado en cursos de desarrollo backend en México.
n8n (automatización): n8n se conecta a cientos de servicios a través de sus APIs REST, permitiendo automatizaciones sin código entre plataformas.
API REST vs GraphQL
| Característica | API REST | GraphQL |
|---|---|---|
| Endpoints | Múltiples (uno por recurso) | Uno solo |
| Datos fetched | Predefinidos por el servidor | El cliente decide qué pide |
| Over-fetching | Común | Eliminado |
| Curva aprendizaje | Baja | Media-alta |
| Ideal para | APIs simples, ecosistemas abiertos | Apps complejas, múltiples clientes |
Errores comunes al diseñar APIs REST
- URLs como verbos en lugar de sustantivos:
/getUserses incorrecto;/userscon GET es REST correcto. - Ignorar los códigos de respuesta HTTP: Devolver siempre 200 incluso cuando hay un error es un anti-patrón. Usa 404 para no encontrado, 400 para bad request, 401 para no autorizado.
- Sin versionado:
/api/v1/userses correcto. Sin versión, romper una API afecta a todos los clientes sin previo aviso. - Sin paginación en colecciones grandes:
GET /productsque devuelve 100,000 productos es un error de diseño. Implementa paginación desde el inicio.
Preguntas Frecuentes (FAQ)
¿Cuál es la diferencia entre API REST y API RESTful?
Técnicamente, REST es el estilo arquitectónico y RESTful es el adjetivo para una API que sigue esos principios completamente. En la práctica, los términos se usan indistintamente en la industria.
¿Necesito REST o GraphQL para mi startup?
Para la mayoría de startups, REST es la elección correcta por su simplicidad, amplio soporte de herramientas y curva de aprendizaje baja. GraphQL se vuelve atractivo cuando tienes múltiples clientes (web, móvil) con necesidades de datos muy diferentes.
¿Cómo testear una API REST?
Las herramientas más populares son Postman (GUI, muy visual) e Insomnia (open source). Para tests automatizados: pytest + requests en Python, Jest en Node.js. Para documentación interactiva: Swagger/OpenAPI es el estándar.
