Principios de diseño de API para aplicaciones web

Principios de diseño de API: Construyendo APIs que los desarrolladores aman

Una API bien diseñada es un placer de usar. Es predecible, consistente y hace lo que el desarrollador espera. Ya sea que estés construyendo una API REST, una API GraphQL o algo más, seguir buenos principios de diseño hace que tu API sea más fácil de aprender, usar e integrar.

La consistencia es clave

El principio más importante del diseño de API es la consistencia. Usa las mismas convenciones de nomenclatura en todas partes — camelCase o snake_case, pero no ambas. Usa el mismo formato de error para cada endpoint. Usa el mismo enfoque de paginación en todas partes. Un desarrollador que ha usado una parte de tu API debería poder adivinar cómo funciona otra parte.

La consistencia también se aplica al comportamiento de los endpoints. Si una solicitud POST crea un recurso, todas las solicitudes POST deben crear recursos. Si una solicitud DELETE devuelve 204 No Content, todas las solicitudes DELETE deben devolver 204. Un comportamiento predecible hace que tu API sea intuitiva.

Diseña para el cliente, no para la base de datos

Es tentador diseñar tus endpoints de API en torno a tus tablas de base de datos. Pero tu API debe servir las necesidades de tus clientes, no reflejar tu esquema de base de datos. Piensa en qué datos necesitan tus clientes y cómo quieren acceder a ellos. Si una aplicación móvil necesita el perfil de un usuario y sus pedidos recientes, proporciona un endpoint que devuelva ambos en una sola respuesta, incluso si provienen de tablas diferentes.

Esto podría significar crear endpoints que agreguen datos de múltiples fuentes. Está bien — la API debería facilitar el trabajo del cliente, no dificultarlo.

Maneja los errores con elegancia

Los errores son inevitables. Una buena API los hace fáciles de entender y manejar. Usa respuestas de error consistentes con una estructura clara. Incluye un código de error que el cliente pueda analizar programáticamente, un mensaje legible por humanos y detalles sobre lo que salió mal. Para errores de validación, indica qué campo era inválido y por qué.

Usa los códigos de estado HTTP correctamente. No devuelvas 200 con un mensaje de error en el cuerpo — usa 400 para solicitudes incorrectas, 401 para fallos de autenticación, 403 para fallos de autorización, 404 para no encontrado y 500 para errores del servidor. El código de estado le dice al cliente lo que sucedió de un vistazo.

Versiona tu API

Tu API cambiará. El versionado te permite hacer cambios sin romper los clientes existentes. El enfoque más simple es incluir la versión en la URL: /api/v1/users, /api/v2/users. Cuando necesites hacer un cambio radical, crea una nueva versión y da tiempo a los clientes para migrar.

Deprecia las versiones antiguas con plazos claros. Incluye un encabezado Sunset en las respuestas de versiones obsoletas para advertir a los desarrolladores. Elimina las versiones antiguas solo después de que haya pasado el período de depreciación.

Documenta a fondo

Una API bien diseñada está documentada. La especificación OpenAPI (anteriormente Swagger) es el estándar para documentar APIs REST. Proporciona una descripción legible por máquina de tu API que se puede usar para generar documentación interactiva, bibliotecas de cliente y suites de pruebas. Una buena documentación incluye ejemplos, describe las respuestas de error y explica el contexto empresarial de cada endpoint.