En una época en que nuevos frameworks aparecen y desaparecen casi a diario, también nacen diferentes enfoques, paradigmas, estilos y arquitecturas que envés de ayudar, lo que hacen muchas veces es generar confusión entre tus desarrolladores. Esto pasa sobretodo cuando tus equipos tienen que programar funcionalidades nuevas. Tu API se va transformando rápidamente en una API demasiado “no-RESTful”, pues su diseño no es lo suficientemente consistente.
Hoy quiero reflexionar contigo sobre “qué hacer para que esto no ocurra” y dejarte algunas “buenas prácticas” que pueden hacer que tu API sea lo más RESTful posible - mientras GraphQL no se haga “standard”! ;)
¿Cuál es el problema...?
Como he comentado anteriormente, hoy día la mayoría de las APIs que se hacen llamar REST ya no son verdaderamente RESTful, si pensamos en las especificaciones REST.
¿... y la solución?
Una solución pasa por seguir unas buenas prácticas y otra - paralela - pasa por implementar HATEOAS.
¿Qué es HATEOAS?
HATEOAS son las siglas de Hypermedia as the Engine of Application State, siendo al mismo tiempo uno de los componentes de REST que lo distingue de las otras arquitecturas.
Es una restricción de REST que guarda en su esencia una idea sencilla y elegante, permitiendo que diseñes APIs REST especificando en sus respuestas como deben ser usadas, proporcionado URLs para las demás acciones permitidas.
Usando palabras de Wikipedia, se trata de un “cliente que interactúa con una aplicación de red completamente a través de hipermedia proporcionadas por los servidores de aplicaciones.”
¿Algún ejemplo?
Imagina que tu organización tiene una API Usuario, representada por la siguiente respuesta:
Si usarais HATEOAS, el JSON se parecería a algo como lo siguiente:
Como puedes ver hemos añadido links. Añadiendo un link a esta representación, en este caso llamado self como el URI para el usuario en causa, le decimos a los clientes de la API como recuperar datos para este usuario.
self es la relación (rel) que explica cómo el link se relaciona con el objeto. Envés de self podrías utilizar perfil con un enlace a la información disponible del perfil del usuario. Para entendernos, si fuera un objeto producto de un e-commerce, la relación podría ser incluso agregarCarrito para agregar un producto al carrito.
href seria la URL completa de la acción de debe ejecutarse. HATEOAS significa “hipermedia como motor del estado de la aplicación”. Por lo tanto, debe haber alguna relación entre la respuesta y el estado de la aplicación. Por eso si, por ejemplo, el usuario no tiene perfil, el JSON podría tener la siguiente estructura:
De esta forma, tu cliente de la API sabe que este usuario no tiene perfil.
Creo que ya puedes imaginar las implicaciones que puede tener HATEOAS para que tu API siga siendo RESTful, pero aquí te dejo algunas más:
- Disminuye la cantidad de configuración necesaria. La aplicación proporciona las URLs de los endpoints y ya no “necesitas” un fichero de configuración hardecoded con estas URLs.
- Promueve el “acoplamiento débil”. Intenta hacer que cambies tus URLs, y sus estructuras de forma relativamente fácil.
- Es una documentación activa que añade valor a los desarrolladores, ya que la API es detectable. Eso sí, tus desarrolladores necesitarán conocerla igualmente, para programar las interacciones.
- Tiene disponible diversas bibliotecas de diferentes lenguajes y frameworks que ayudan a seguir el principio HATEOAS. PHP HATEOAS REST, Express HATEOAS Links y Spring HATEOAS son algunos ejemplos.
¿Qué más debo hacer para que mi API siga siendo RESTful?
Creo que respetar HATEOAS ya es un buen comienzo. Aquí tienes algunas buenas prácticas más para diseñar tu API RESTful:
Keep it Simple - Simplifica
Como hemos visto en las imágenes de este artículo, es importante asegurar que la URL base de la API sea simple. Puedes usar, por ejemplo, “/usuarios” para obtener todos los usuarios y “/usuarios/123” para obtener un usuario específico.
Utiliza nombres y no verbos
Para obtener todos los usuarios, debes utilizar “usuarios” y no “obtenerTodosUsuarios”, por ejemplo. No utilizar verbos es una buena idea, pues los métodos de petición HTTP ya lo hacen.
Utiliza los métodos de petición HTTP correctos
Usa:
- GET para obtener un recurso o una colección de recursos
- POST para criar un recurso o una colección de recursos
- PUT o PATCH para actualizar un recurso existente o una colección de recursos
- DELETE para eliminar un recurso existente
Usa parámetros
Tal como en los “nombres y no verbos”, debes usar parámetros cuando necesites hacer una consulta que no sea por el id. Por ejemplo: “/usuarios?nombre=’Juan’ y no “/getUsuariosPorNombre”. Esto te permite respetar la primera práctica: simplifica.
Usa el código HTTP adecuado
En HTTP hay vida más allá de los códigos 200 y 500. Si quieres que tu API sea RESTful, deberás utilizar los demás códigos HTTP y devolverlos según el caso. Por ejemplo:
- 210 CREATED. Si usas POST y has podido crear un nuevo recurso.
- 401 UNAUTHORIZED / 403 FORBIDDEN. Si el usuario o el sistema no pueden ejecutar determinada operación.
- 404 NOT FOUND. Para utilizarlo si el recurso no existe en el sistema.
- 502 BAD GATEWAY. Puedes utilizarlo si el servidor ha recibido alguna respuesta no válida.
Usa las especificaciones de Open API
Las especificaciones de Open API son útiles porque permiten que todos tus equipos cumplan con ciertos principios. Además, ayudan a agilizar el proceso de construcción de tu API manteniendo su diseño, documentación e implementación sincronizados y actualizados automáticamente. ¡Tus clientes lo agradecerán!
Conclusión
Estarás de acuerdo que seguir las buenas prácticas de REST permite mejorar tu sistema, sobretodo porque te obliga a respetar principios de desarrollo que son principios clave para sistemas de calidad.
Pero claro, todo tiene un precio. Entender y estudiar tu producto sigue siendo clave para tomar la mejor decisión. Recuerda que el objetivo es comunicar mejor. Seguir las buenas prácticas no solo permitirá mantener tu API RESTful, pero también evitará la confusión relacionada con el diseño de tu aplicación.
¿La API REST de tu organización es completamente RESTful? ¿En qué momento de la historia lo dejó de ser? ¿Por qué motivo?
Fuentes:
