4. Implementación de SyncBoards
4.3 Servidor de la aplicación de administración de tableros
4.3.5 Interfaz de comunicación
Con el propósito de proveer una aplicación que permita ser simplemente extendida o integrada en otras herramientas, se implementó una interfaz de comunicación. Esta interfaz consiste de un API REST
En el contexto de una aplicación web, se implementa este API mediante la definición de una serie de direcciones URL, conocidas comoendpoints
. Cada solicitud realizada a un
endpoint contiene un verbo HTTP asociado [31]. Este verbo identifica la acción a realizar en cada endpoint.
En el paquete Routes se definen todos los endpoints necesarios y el verbo HTTP que tienen asociado. Para definir la acción a realizar, este paquete se comunica con el paquete Controllers
.
El paqueteControllers tiene como objetivo principal definir la acción a realizar en cada endpoint. Además, especifica los permisos necesarios que se deben tener para accederlo.
En cada solicitud de un endpoint que requiera permisos de acceso, se debe incluir el access-token del usuario. Éste debe ser incluido en un campo de la cabecera de la solicitud HTTP. Siguiendo el estándar RFC2617 [32], la llave del campo de la cabecera debe serAuthorization
. Por su parte, el cuerpo del campo debe comenzar con el texto
Bearer
, y luego, separado por un espacio, se debe incluir el access-token del usuario
[27].
En la figura 4.12 se muestra el diagrama con las clases incluidas en los paquetes Routes y Controllers.
Figura 4.12 - Diagrama de clases de los paquetes Routes y Controllers.
La respuesta a cada solicitud de un endpoint, tendrá asociado un código de estado en la cabecera HTTP. La definición de estos códigos se basó en el estándar RFC 7231 [33]. En la tabla 4.1 se detalla el significado de los códigos utilizados.
Código de
estado HTTP Categoría
Frase de
motivo Significado
200 Exitoso OK La solicitud ha sido exitosa.
201 Exitoso Created La solicitud ha sido exitosa y un nuevo elemento ha sido creado. 204 Exitoso No Content La solicitud ha sido exitosa pero la
400 Error de
cliente Bad Request
La solicitud contiene errores y el servidor no la procesará.
401 Error de
cliente Unauthorized
Se requiere una autenticación, pero no se ha especificado ninguna.
403 Error de
cliente Forbidden
Se ha especificado una autenticación, pero no cuenta con
los permisos necesarios para completar la solicitud.
404 Error de
cliente Not Found
El recurso solicitado no ha sido encontrado en el servidor.
500 Error de
servidor
Internal Server Error
Se han producido errores durante el procesamiento de la solicitud.
Tabla 4.1 - Códigos de estado utilizados en las cabeceras HTTP.
En la clase AuthRoutes se definen los endpoints necesarios para dar lugar a la autenticación de usuarios. Cada endpoint tiene asociado un método de la clase
AuthController
. Este controlador, por un lado, tiene la responsabilidad de redireccionar
a un usuario a un servicio externo con el fin de comenzar el flujo de autenticación. Por el otro lado, tiene la responsabilidad de completar el flujo de autenticación detallado en la sección 4.3.2, respondiendo al usuario con el código de requerimiento de access-token.
La claseUserRoutes
define los endpoints utilizados para la administración de usuarios.
Con la única excepción del endpoint de requerimiento de access-token, los endpoints de usuarios requieren el uso de un access-token válido y asociado al usuario que se desea administrar. De no incluirse un access-token cuando es requerido, la respuesta a la solicitud tendrá el código de estado HTTP 401. Por otro lado, si el access-token no se corresponde con el usuario, la respuesta tendrá el código de estado HTTP 403. Cada endpoint tiene asociado un método de la clase UsersController
. Este controlador
tiene como objetivos principales, permitir la lectura y escritura de la información de los usuarios, y el control de permisos para realizar dichas acciones.
desarrollo en particular, se debe incluir el access-token asociado al usuario creador de dicho equipo. En el caso del endpoint de creación de equipos, cualquier access-token es aceptado.
Cada endpoint tiene asociado un método de la claseTeamsController
. Este controlador
tiene como objetivos principales, permitir la creación, actualización y obtención de información de los equipos de desarrollo. Además, permite al creador del equipo, agregar nuevos usuarios a dicho equipo.
La clase BoardRoutes define los endpoints necesarios para dar lugar a la administración de tableros digitales. Con el fin de utilizar un endpoint asociado a un tablero digital, se debe incluir el access-token asociado al usuario creador del tablero, o el access-token de cualquier miembro del equipo de desarrollo asociado. En el caso del endpoint de creación de tableros digitales cualquier access-token es aceptado.
Cada endpoint posee un método asociado en la clase BoardsController
. Este
controlador tiene como objetivos principales permitir tanto la creación y actualización de tableros, como la obtención de la información de los mismos. Además, permite importar la imagen de un tablero físico, y crear la versión imprimible del tablero digital.
En la clase RelationRoutes se definen los endpoints que dan lugar a la administración de relaciones. Para poder hacer uso de los endpoints asociadas a una relación, se debe incluir el access-token de un usuario con permisos de acceso al tablero al que pertenece dicha relación.
Cada endpoint tiene un método asociado en la clase RelationsController
. Este
controlador tiene como objetivo principal, permitir tanto la creación, actualización y eliminación de relaciones, como la obtención de información de las mismas.
La clase ItemRoutes define los endpoints que dan lugar a la administración de ítems. Para poder hacer uso de los endpoints asociados a un ítem, se debe incluir el access-token de un usuario que posea permisos de acceso al tablero en el cual se
Cada endpoint tiene un método asociado en la clase ItemsController
. Este controlador
tiene como objetivo principal, permitir tanto la creación, actualización y eliminación de ítems, como la obtención de información de los mismos.