API REST: conceptos fundamentales

Una API es una interfaz que permite que dos sistemas intercambien información o ejecuten operaciones de forma estructurada.

En una API web, un cliente realiza una petición HTTP y un servidor responde con datos, normalmente en formatos como JSON.

Cliente ↓
Petición HTTP ↓
API ↓
Lógica / Datos ↓
Respuesta HTTP ↓
Cliente

REST es un estilo arquitectónico para sistemas distribuidos. Una API que utiliza HTTP no es automáticamente una API REST: debe respetar una serie de principios y convenciones.

Una petición HTTP puede contener varios elementos.

• Método HTTP.
• URI.
• Headers.
• Parámetros.
• Cuerpo de la petición cuando sea necesario.

Ejemplo conceptual:

POST /api/productos HTTP/1.1
Host: api.ejemplo.com
Content-Type: application/json
Authorization: Bearer <token> { "nombre": "Teclado", "precio": 49.90}

En este caso, el cliente solicita crear un producto y envía los datos en formato JSON.

El significado concreto de PUTy PATCHpuede depender del diseño de la API, pero conviene mantener una semántica coherente y documentada.

El código debe describir el resultado real de la operación. Devolver siempre 200, incluso cuando existe un error, dificulta el uso y mantenimiento de la API.

Los headers transportan información adicional sobre la petición o la respuesta.

Ejemplo:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

Los endpoints que devuelven colecciones suelen necesitar mecanismos para controlar la cantidad y el orden de los datos.

Filtrado:

GET /productos?activo=true

Ordenación:

GET /productos?sort=precio

Paginación:

GET /productos?page=2&limit=20

No existe una única convención universal para estos parámetros. Lo importante es definir un criterio coherente y documentarlo.

Autenticaciónresponde a la pregunta: ¿quién eres?

Autorizaciónresponde a la pregunta: ¿qué puedes hacer?

Una API puede utilizar distintos mecanismos de autenticación. Un ejemplo habitual es transmitir un token mediante el header Authorization.

Authorization: Bearer <token>

El diseño de autenticación requiere medidas adicionales como HTTPS, validación de tokens, expiración, protección de credenciales y control de permisos.

Nunca deben incluirse secretos reales en ejemplos, repositorios o documentación pública.

Una API resulta más sencilla de consumir cuando los errores utilizan una estructura uniforme.

Por ejemplo:

{ "error": "validation_error", "message": "Los datos enviados no son válidos.", "details":{ "precio": "Debe ser mayor que cero."}}

El formato concreto puede variar, pero mantener una estructura estable facilita que los clientes gestionen los errores correctamente.

HTTP dispone de mecanismos de caché que pueden reducir peticiones innecesarias y mejorar el rendimiento.

Por ejemplo:

Cache-Control: public, max-age=3600

No todas las respuestas deben almacenarse en caché. Datos privados o altamente dinámicos requieren políticas adecuadas a su contexto.

Diseña conceptualmente una API para gestionar tareas con estos campos:

{ "id": 1, "titulo": "Preparar documentación", "completada": false}

Define los endpoints necesarios para:

1. Consultar todas las tareas.
2. Consultar una tarea por ID.
3. Crear una tarea.
4. Modificar su título.
5. Marcarla como completada.
6. Eliminarla.

Una posible propuesta sería:

Como ampliación, define qué códigos HTTP debería devolver cada endpoint en caso de éxito y en situaciones de error.

• Diseña rutas coherentes y orientadas a recursos.
• Utiliza correctamente la semántica de los métodos HTTP.
• Devuelve códigos de estado representativos.
• Mantén formatos de respuesta consistentes.
• Valida siempre los datos recibidos.
• Implementa autenticación y autorización según el riesgo del servicio.
• Utiliza HTTPS para proteger el tráfico en entornos reales.
• Evita exponer información interna en mensajes de error.
• Implementa paginación en colecciones grandes.
• Documenta parámetros, cuerpos, respuestas y errores.
• Considera compatibilidad antes de modificar el contrato de una API publicada.

Esta guía resume conceptos fundamentales para comprender y diseñar APIs HTTP. Para profundizar conviene consultar las especificaciones y documentación técnica.

• HTTP en MDN Web Docs
• Métodos HTTP en MDN
• Códigos de estado HTTP en MDN