Mejores prácticas de diseño de API REST

Diseñar APIs REST que la gente disfrute usar

Una API bien diseñada es un placer de usar. Es predecible, consistente y hace lo que esperas. REST (Transferencia de Estado Representacional) es el estilo arquitectónico más común para diseñar APIs, y seguir sus convenciones hace que tu API sea más fácil de aprender, usar y mantener.

Piense en términos de recursos, no de acciones

La idea central de REST es modelar tu API en torno a recursos — las cosas que tu sistema gestiona, como usuarios, pedidos, productos o artículos. Cada recurso tiene una URL que lo identifica. Usas métodos HTTP para indicar lo que quieres hacer: GET para recuperar, POST para crear, PUT para reemplazar, PATCH para actualizar y DELETE para eliminar.

Las URL deben ser sustantivos, no verbos. Use /users en lugar de /getUsers, y /orders en lugar de /createOrder. Los recursos pueden anidarse para mostrar relaciones: /users/123/orders representa los pedidos del usuario 123. Esto hace que tu API sea intuitiva — los desarrolladores pueden adivinar las URL sin leer la documentación.

Use los códigos de estado HTTP correctamente

Los códigos de estado HTTP son tu forma de decirle al cliente qué pasó. 200 significa que todo funcionó. 201 significa que se creó un recurso (y debes incluir un encabezado Location que apunte a él). 204 significa que la solicitud tuvo éxito pero no hay contenido que devolver. 400 significa que el cliente envió algo inválido. 401 significa que necesita autenticarse. 403 significa que no tiene permiso. 404 significa que no se encontró el recurso. 429 significa que ha sido limitado en la tasa de solicitudes. Y 500 significa que algo salió mal en el servidor.

Usar los códigos de estado correctos de manera consistente hace que tu API sea mucho más fácil de depurar. Los clientes pueden manejar errores mediante programación en lugar de analizar mensajes de error. Herramientas como clientes HTTP y bibliotecas de API pueden proporcionar mejores comentarios cuando entienden los códigos de estado.

Versiona tu API desde el primer día

Incluso si crees que tu API es perfecta, eventualmente necesitarás cambiarla. El versionado te permite hacer cambios sin romper 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 disruptivo, creas una nueva versión y das tiempo a los clientes para migrar.

Una vez que una versión está obsoleta, incluya un encabezado Sunset en las respuestas para advertir a los clientes que la versión antigua eventualmente será eliminada. Esto les da tiempo para actualizarse.

Maneje la paginación, el filtrado y la ordenación

Cuando una API devuelve una lista de recursos, debe soportar paginación para que los clientes puedan solicitar datos en fragmentos manejables. La paginación basada en cursor es más eficiente que la basada en páginas para grandes conjuntos de datos. Permita a los clientes filtrar resultados por campos comunes, y permítales especificar el orden de clasificación. Incluya metadatos en la respuesta para que los clientes sepan cómo obtener la siguiente página.

Devuelva respuestas de error coherentes

Cuando algo sale mal, tu API debe devolver una estructura de error coherente que los clientes puedan analizar. Incluya un código de error, un mensaje legible por humanos y detalles sobre lo que salió mal. Para errores de validación, indique qué campo no fue válido y por qué. Existe un formato estándar llamado RFC 7807 (Detalles del problema para APIs HTTP) que muchas APIs siguen.

Asegure su API

Use tokens de portador (como JWT) en el encabezado Authorization para la autenticación. Use claves API para la comunicación entre servidores. Para acceso delegado, implemente OAuth 2.0. Siempre limite la tasa de solicitudes por cliente para evitar abusos. Y registre cada solicitud para auditoría y depuración.

Documente y pruebe

Una buena API está documentada. La especificación OpenAPI (anteriormente Swagger) es la forma estándar de describir APIs REST. Las herramientas pueden generar documentación interactiva, bibliotecas de cliente y suites de pruebas a partir de su especificación OpenAPI. Las pruebas de contrato aseguran que su API se comporte como se documenta, y los servidores simulados permiten a los clientes desarrollar contra su API antes de que esté lista.