Mi aproximación al diseño de APIs RESTful
El diseño de APIs siguiendo el estilo arquitectónico REST es tema de debate constante en la red. Existen innumerables publicaciones sobre el tema tanto post personales como artículos respaldados por organizaciones. Separar la paja del grano en este tema es difícil dado que la fuente canónica de información son documentos académicos. Me encantaría leer algo mas aterrizado a la práctica del mismo Roy Fielding pero respeto su compromiso con la comunidad y su incansable trabajo en los procesos de estandarización. En este post voy a compartir con ustedes mi propia aproximación al problema. La parte en negritas sería la descripción necesaria de la API.
El caso de estudio para este post será la clásica aplicación de Cosas Por Hacer.
Lo primero es modelar el recurso Cosa Por Hacer o Todo como se le conoce en Ingles. Aquí vamos a asumir que es algo tan simple como que tiene 2 atributos: el titulo y la bandera de completado.
Lo segundo sería identificar las acciones y el posible flujo del usuario entre ellas. En este caso se parte de una lista de Cosas Por Hacer de las cuales el usuario puede escoger ver solo las que están pendientes o las que ya se han realizado. En esta lista las acciones posibles serian dos: crear una nueva Cosa Por Hacer o marcar una Cosa Por Hacer como que ya se ha realizado.
Como se puede ver existe un elemento central que es la visualización de las Cosas Por Hacer. De esto se desprende que el diseño de una API para resolver este problema se beneficiaría de la existencia de un recurso que fuera la lista de todas las Cosas Por Hacer. Aunque esto por si solo no es suficiente, sino que es necesario la existencia del recurso Cosa Por Hacer puntual para poder marcarlo individualmente como realizado.
Una vez que tenemos identificados los recursos que forman parte de la API podemos pasar a identificar las relaciones necesarias para establecer el flujo de interacciones del usuario. En este caso solo existen dos relaciones necesarias: La relación especial "self" para el recurso Cosa Por Hacer y la relación "pertenece-a-lista" que es específica para esta aplicación. De esta forma es posible navegar desde la lista de Cosas Por Hacer hasta una de ellas para marcarla como completada. Adicionalmente es posible navegar desde una Cosa Por Hacer a la lista a la que pertenece.
Un ultimo elemento a tratar con respecto a las relaciones es el recurso raíz. El único punto conocido de acceso a la API, puede ser la URL raíz de un host o no. En este caso el recurso raíz podría ser un recurso adicional o la misma lista de Cosas Por Hacer. Lo mas sencillo sería que el recurso raíz de la API fuera la misma lista de Cosas Por Hacer (lo que vamos a demostrar en este post), pero esto limita la API a una sola lista. En mi caso generalmente hago al recurso raíz de la API una cosa aparte para ofrecer información acerca de la implementación del servidor y adiciono una relación (en este caso por ejemplo "tiene-lista") para poder navegar desde el recurso raíz hacia una lista de Cosas Por Hacer. Incorporando una colección en el recurso raíz podemos implementar varias listas de Cosas Por Hacer en una misma API.
Que tipos MIME usar en la API es un elemento crucial, pues si estos no son tipos Hypermedia no será posible crear una verdadera API REST. Personalmente uso el tipo MIME HAL especificamente la variante JSON. Los ejemplos de uso de la API serán usando este tipo MIME. El problema con este tipo MIME es que es genérico y por tanto es necesaria una descripción de la entidad. En este caso solo es necesario aclarar los nombres de los atributos: title para el título y fullfilled para la bandera de completado. El otro tipo MIME a especificar es el usado para modificar una Cosa Por Hacer. Personalmente uso el tipo JavaScript Object Notation (JSON) Patch el cual se ajusta a este caso de uso conjugado con el método PATCH.
Hasta aquí la descripción de la API. En una próxima entrada de demostrará una implementación de esta descripción.
El caso de estudio para este post será la clásica aplicación de Cosas Por Hacer.
Lo primero es modelar el recurso Cosa Por Hacer o Todo como se le conoce en Ingles. Aquí vamos a asumir que es algo tan simple como que tiene 2 atributos: el titulo y la bandera de completado.
Lo segundo sería identificar las acciones y el posible flujo del usuario entre ellas. En este caso se parte de una lista de Cosas Por Hacer de las cuales el usuario puede escoger ver solo las que están pendientes o las que ya se han realizado. En esta lista las acciones posibles serian dos: crear una nueva Cosa Por Hacer o marcar una Cosa Por Hacer como que ya se ha realizado.
Como se puede ver existe un elemento central que es la visualización de las Cosas Por Hacer. De esto se desprende que el diseño de una API para resolver este problema se beneficiaría de la existencia de un recurso que fuera la lista de todas las Cosas Por Hacer. Aunque esto por si solo no es suficiente, sino que es necesario la existencia del recurso Cosa Por Hacer puntual para poder marcarlo individualmente como realizado.
Una vez que tenemos identificados los recursos que forman parte de la API podemos pasar a identificar las relaciones necesarias para establecer el flujo de interacciones del usuario. En este caso solo existen dos relaciones necesarias: La relación especial "self" para el recurso Cosa Por Hacer y la relación "pertenece-a-lista" que es específica para esta aplicación. De esta forma es posible navegar desde la lista de Cosas Por Hacer hasta una de ellas para marcarla como completada. Adicionalmente es posible navegar desde una Cosa Por Hacer a la lista a la que pertenece.
Un ultimo elemento a tratar con respecto a las relaciones es el recurso raíz. El único punto conocido de acceso a la API, puede ser la URL raíz de un host o no. En este caso el recurso raíz podría ser un recurso adicional o la misma lista de Cosas Por Hacer. Lo mas sencillo sería que el recurso raíz de la API fuera la misma lista de Cosas Por Hacer (lo que vamos a demostrar en este post), pero esto limita la API a una sola lista. En mi caso generalmente hago al recurso raíz de la API una cosa aparte para ofrecer información acerca de la implementación del servidor y adiciono una relación (en este caso por ejemplo "tiene-lista") para poder navegar desde el recurso raíz hacia una lista de Cosas Por Hacer. Incorporando una colección en el recurso raíz podemos implementar varias listas de Cosas Por Hacer en una misma API.
Que tipos MIME usar en la API es un elemento crucial, pues si estos no son tipos Hypermedia no será posible crear una verdadera API REST. Personalmente uso el tipo MIME HAL especificamente la variante JSON. Los ejemplos de uso de la API serán usando este tipo MIME. El problema con este tipo MIME es que es genérico y por tanto es necesaria una descripción de la entidad. En este caso solo es necesario aclarar los nombres de los atributos: title para el título y fullfilled para la bandera de completado. El otro tipo MIME a especificar es el usado para modificar una Cosa Por Hacer. Personalmente uso el tipo JavaScript Object Notation (JSON) Patch el cual se ajusta a este caso de uso conjugado con el método PATCH.
Hasta aquí la descripción de la API. En una próxima entrada de demostrará una implementación de esta descripción.
Comments
Post a Comment