Metodología para migrar aplicaciones web a CMS: el caso de un
Anuncio
TRABAJO FIN DE GRADO Título Metodología para migrar aplicaciones web a CMS: el caso de un gestor de noticias Autor/es Lucian Adrian Dan Director/es Julio Rubio García Facultad Facultad de Ciencias, Estudios Agroalimentarios e Informática Titulación Grado en Ingeniería Informática Departamento Curso Académico 2012-2013 Metodología para migrar aplicaciones web a CMS: el caso de un gestor de noticias, trabajo fin de grado de Lucian Adrian Dan, dirigido por Julio Rubio García (publicado por la Universidad de La Rioja), se difunde bajo una Licencia Creative Commons Reconocimiento-NoComercial-SinObraDerivada 3.0 Unported. Permisos que vayan más allá de lo cubierto por esta licencia pueden solicitarse a los titulares del copyright. © © El autor Universidad de La Rioja, Servicio de Publicaciones, 2013 publicaciones.unirioja.es E-mail: [email protected] UNIVERSIDAD DE LA RIOJA Facultad de Ciencias, Estudios Agroalimentarios e Informática TRABAJO FIN DE GRADO Grado en Ingeniería Informática Metodología para migrar aplicaciones web a CMS: el caso de un gestor de noticias Alumno: Dan Lucian Adrian Director: Julio Rubio García Logroño, (Junio, 2013) Trabajo Fin de Grado Página 1 Introduccion A la vista de las estadísticas del porcentaje de número de aplicaciones web desarrolladas hoy en día, en los distintos lenguajes de programación, y teniendo en cuenta el auge de los gestores de contenidos que facilitan tanto el desarrollo como el futuro mantenimiento de una aplicación web, se ha decidido dedicar una parte de este proyecto en detallar los pasos que conlleva el pasar una aplicación web hecha sin la ayuda de ningún gestor a uno muy conocido como puede ser Joomla o Wordpress. Para ello tomaremos como proyecto base el Proyecto Fin de Carrera “Gestión documental de las actividades de un Servicio de Comunicación” desarrollado en su día en asp/mysql/tomcat. Trabajo Fin de Grado Página 2 Tabla de Contenido: 1. Documento de objetivos del proyecto ...................................................................................... 7 1.1 Descripción del producto .................................................................................................... 7 1.2 Alcance del proyecto ........................................................................................................... 7 1.2.1 Detallar los pasos para cambiar a un proyecto basado en herramientas de gestión de contenido .............................................................................................................................. 7 1.2.2 Listas de subscripción a las noticias ............................................................................. 8 1.2.3 Proteger el apartado de gestión de la aplicación mediante SSL .................................. 8 1.2.4 API REST........................................................................................................................ 8 1.2.5 Terminales móviles (Android) ...................................................................................... 9 1.3. Recursos humanos y personales ........................................................................................ 9 1.4. Plan de comunicación ........................................................................................................ 9 1.5. Dirección de riesgos ........................................................................................................... 9 1.6. Planificación del proyecto ................................................................................................ 10 1.6.1 Detallar los pasos para cambiar a un proyecto basado en herramientas de gestión de contenido (Iteración 1) ........................................................................................................ 10 1.6.2 Listas de subscripción a las noticias (Iteración 2)....................................................... 10 1.6.3 Proteger el apartado de gestión de la aplicación mediante SSL (Iteración 3) ........... 11 1.6.4 API REST (Iteracion 4) ................................................................................................. 11 1.6.5 Terminales móviles (Iteración 5) ................................................................................ 11 1.6.6 Documentación (Iteración 0) ..................................................................................... 12 1.6.7 Total............................................................................................................................ 12 1.7. Listado de entregables ..................................................................................................... 12 1.8. Revisión del DOP .............................................................................................................. 12 2. Análisis Iteración 1 .................................................................................................................. 12 2.1 Alcance .............................................................................................................................. 12 2.2 Objetivos ........................................................................................................................... 13 2.3 Entregables........................................................................................................................ 13 2.4 Aprendizaje ....................................................................................................................... 13 2.5 Descripción ........................................................................................................................ 14 2.5.1 Definiciones ................................................................................................................ 14 2.5.2 Seguridad.................................................................................................................... 14 2.5.3 Funcionalidades de la aplicación ................................................................................ 14 Trabajo Fin de Grado Página 3 2.6 Documentación de referencia y anexos ............................................................................ 16 3. Diseño Iteración 1 ................................................................................................................... 17 3.1 Instalación ......................................................................................................................... 17 3.2 Funcionalidades................................................................................................................. 17 3.2.1 Inicio de sesión ........................................................................................................... 17 3.2.2 Registrar ..................................................................................................................... 18 3.2.3 Finalizar sesión ........................................................................................................... 18 3.2.4 Página de Inicio .......................................................................................................... 18 3.2.5 Filtrar noticias............................................................................................................. 19 3.2.6 Publicar noticias ......................................................................................................... 19 3.2.7 Editar noticias ............................................................................................................. 20 3.2.8 Eliminar noticia........................................................................................................... 20 3.2.9 Descargar noticia - frontend ....................................................................................... 20 4. Implementación Iteración 1 .................................................................................................... 20 4.1 Idiomas .............................................................................................................................. 20 4.2 Múltiples categorías .......................................................................................................... 21 5. Análisis Iteración 2 .................................................................................................................. 21 5.1 Alcance .............................................................................................................................. 21 5.2 Objetivos ........................................................................................................................... 22 5.3 Entregables........................................................................................................................ 22 5.4 Descripción ........................................................................................................................ 22 6. Diseño e implementación Iteración 2 ..................................................................................... 22 7. Análisis Iteración 3 .................................................................................................................. 23 7.1 Alcance .............................................................................................................................. 23 7.2 Proteger el apartado de gestión de la aplicación mediante SSL ....................................... 23 7.2.1 Configuración personal .............................................................................................. 23 8. Análisis Iteración 4 .................................................................................................................. 24 8.1 Alcance .............................................................................................................................. 24 8.2 Objetivos ........................................................................................................................... 24 8.3 Perspectiva general de la solución .................................................................................... 24 8.4 Seguridad, Fiabilidad y Disponibilidad .............................................................................. 24 8.5 Funcionalidades de la aplicación. ...................................................................................... 25 8.5.1 Listado de Noticias ..................................................................................................... 25 8.5.2 Listado de Categorías ................................................................................................. 25 Trabajo Fin de Grado Página 4 8.5.3 Listado de Alertas ....................................................................................................... 25 8.5.4 Filtrado de Noticias .................................................................................................... 26 8.5.5 Detalle de noticia ....................................................................................................... 26 8.5.6 Alta de las listas de suscripción (alertas).................................................................... 26 8.5.7 Baja de las listas de suscripción (alertas) ................................................................... 26 9. Diseño Iteración 4 ................................................................................................................... 26 9.1 Objeto del documento ...................................................................................................... 26 9.2 Definiciones, acrónimos y abreviaturas ............................................................................ 26 9.3 API ..................................................................................................................................... 27 9.4 Sitio web de la API ............................................................................................................. 27 9.4.1 Entorno desarrollo/producción.................................................................................. 27 9.5 Parámetros de entrada comunes ...................................................................................... 27 9.6 Formato de llamada .......................................................................................................... 28 9.7 Formato de respuesta ....................................................................................................... 29 9.8 Métodos del API ................................................................................................................ 29 9.8.1 Listado de noticias ...................................................................................................... 29 9.8.2 Listado de Categorías ................................................................................................. 30 9.8.3 Listado de Alertas ....................................................................................................... 31 9.8.4 Filtrado de noticias ..................................................................................................... 31 9.8.5 Detalle de noticia ....................................................................................................... 32 9.8.6 Alta de las listas de suscripción (alertas).................................................................... 33 9.8.7 Baja de las listas de suscripción (alertas) ................................................................... 33 9.9 Aspectos de seguridad ...................................................................................................... 33 9.9.1 Validaciones/Seguridad del API.................................................................................. 34 9.10 Modulado funciones ....................................................................................................... 36 9.10.1 Módulo api_noticias ................................................................................................. 36 9.10.2 Módulo api_categorías............................................................................................. 37 9.10.3 Módulo api_alertas .................................................................................................. 38 9.11 Vista de Datos.................................................................................................................. 38 9.11.1 Modelo de base datos .............................................................................................. 38 10. Implementación Iteración 4 .................................................................................................. 39 10.1 Pasos................................................................................................................................ 40 10.1.1 Centralizar peticiones ............................................................................................... 40 10.1.2 Procesar petición...................................................................................................... 40 Trabajo Fin de Grado Página 5 10.1.3 Versionado ............................................................................................................... 40 10.1.4 Recursos, objetos, clases .......................................................................................... 41 10.2 Componentes .................................................................................................................. 41 10.2.1 Carpetas base ........................................................................................................... 41 10.2.2 Carpeta Objetos ....................................................................................................... 41 11. ANEXOS ................................................................................................................................. 42 11.1 Códigos de Error API........................................................................................................ 42 11.2 REST - REpresentational State Transfer .......................................................................... 43 11.2.1 Ejemplo CRUD .......................................................................................................... 44 11.2.2 Ejemplo POST ........................................................................................................... 45 11.3 Ejemplo petición post api REST ....................................................................................... 45 11.3.1 Petición..................................................................................................................... 45 11.3.2 Notas ........................................................................................................................ 46 Trabajo Fin de Grado Página 6 1. Documento de objetivos del proyecto 1.1 Descripción del producto El objetivo de este proyecto es analizar los pasos necesarios para pasar de una aplicación desarrollada sin la ayuda de ningún gestor de contenido a una que se base en ellos. Como caso práctico nos basaremos en la aplicación web desarrollada en el Proyecto Fin de Carrera “Gestión documental de las actividades de un Servicio de Comunicación”. Una vez analizados y desarrollados los pasos se implementaran funcionalidades en varias iteraciones que serán limitadas al tiempo preestablecido que limita el desarrollo de un Trabajo Fin de Grado. 1.2 Alcance del proyecto Para el desarrollo de este proyecto se ha elegido el CMS(Content Management System) Joomla por la experiencia personal que me ha tocado vivir en el trabajo al migrar empresas de clientes recién adquiridas, y por continuas preguntas que me encuentro en mi día a día por parte de amigos al preguntarme si les puedo ayudar con proyectos en Joomla. Se ha decidido no hacer un estudio con respecto a cuál sería el mejor CMS ya que dicho estudio probablemente llevaría más de la mitad del tiempo disponible para dedicar a este proyecto y las diferencias serian mínimas entre las primeras soluciones posibles. El proyecto se desarrollará en iteraciones teniendo como base la que se encarga de pasar el proyecto antes mencionado al gestor de contenido elegido, todas las demás iteraciones ampliarán el proyecto hasta acabadas las horas de dedicación asignadas a un proyecto Fin de Grado no teniendo en ningún momento como objetivo implementar todas las iteraciones si estas ocupan más tiempo que el establecido. A continuación se hará un resumen de las partes que se tratarán en cada iteración. 1.2.1 Detallar los pasos para cambiar a un proyecto basado en herramientas de gestión de contenido Se pasará el Proyecto Fin de Carrera “Gestión documental de las actividades de un Servicio de Comunicación”, desarrollado en asp, a php5 utilizando el esqueleto de aplicación web que ofrece Joomla. Para ello se detallarán los siguientes pasos teniendo como objetivo reutilizar cuanto más código de la aplicación anterior mejor: a. Analizar y detallar los pasos necesarios para replicar la estructura de tablas utilizadas en el antiguo proyecto a la estructura de tablas que utiliza Joomla. En este apartado se concretará si se siguen utilizando los procedimientos almacenados del antiguo proyecto o se optará por otra solución. Si en este paso no se puede mantener alguna estructura de la BD original, ella se modificará para cumplir con los criterios de Joomla. b. Detallar el paso de una acción normal como “creación de una noticia” a la forma de creación de Joomla que utiliza plantillas, vistas, acciones. c. Detallar la creación de un plugin personalizado de la aplicación para dar soporte a funcionalidades que el propio Joomla no ofrece. Se planteará la idea de crear un plugin para la generación de PDF. Si existe ya algún plugin que Trabajo Fin de Grado Página 7 ofrece una funcionalidad parecida se utilizará como base para el plugin personalizado. d. Se utilizará algún plugin existente para dar soporte al apartado de visualización de las noticias en formato multimedia. e. Para el desarrollo de la interfaz web se utilizará la idea de “960 Grid system” para darle robustez y amigabilidad a la aplicación. Objetivo: Detallar los pasos seguidos para pasar una aplicación web a un CMS. Cómo implementar funcionalidades básicas o complejas mediante plugins. Utilización del “960 Grid system” para la interfaz de usuario. El objetivo de la primera parte no es el de pasar el 100% de la aplicación web utilizada como ejemplo sino solo las funciones necesarias para el ejemplo y para poder seguir ampliando el proyecto en las siguientes iteraciones. Para ello se considerarán necesarias las funcionalidades básicas de creación, eliminación, modificación, listado de los elementos que se gestionan desde el apartado de administración de la antigua aplicación como pueden ser noticias, dossiers, géneros, etc. Solamente se desarrollarán funcionalidades avanzadas como reproducción de contenidos multimedia para poder explicar la correspondiente parte de la primera iteración. 1.2.2 Listas de subscripción a las noticias Se creara una lista de subscripción a las noticias, en la cual los usuarios se podrán dar de alta para recibir avisos mediante mensajes de la existencia de nuevo contenido en la aplicación. Dicho apartado será accesible mediante la web. Se creará un apartado desde el cual los usuarios registrados podrán darse de alta en un sistema de alertas predefinidas. Tendrán la posibilidad de darse de alta o de baja cuando lo desean desde su área de cliente. Se creará una plantilla para los correos que se enviarán a los clientes. Cada uno de los correos con noticias que se enviarán al cliente estarán en formato HTML y tendrán URL que te permitirá el acceso a la web de las noticias, y además información con respecto a los contenidos nuevos agregados. 1.2.3 Proteger el apartado de gestión de la aplicación mediante SSL Se configurará la parte de gestión de la aplicación con SSL. Para ello se creará un certificado propio que utilizaremos para la comunicación cliente/servidor en la parte de gestión. 1.2.4 API REST Implementar un API REST para que clientes desde otros dispositivos puedan disfrutar de los servicios que la aplicación ofrece montando su propia interfaz basándose en los servicios web del API. Este API solamente dará soporte a noticias en formato de textos sin implicar los ficheros adjuntos tanto multimedia como documentos normales. Funcionalidades que estarán disponibles: Trabajo Fin de Grado Página 8 Listado de noticias. Detalle de noticia. Filtrado. Subscripción a listas de la iteración anterior. Se crearán funciones que solamente serán accesibles a usuarios dados de alta desde el apartado de gestión de la aplicación. A dichas funciones se les tendrán que pasar datos necesarios para la autenticación. Valorar noticia. Baja de la lista de subscripción. 1.2.5 Terminales móviles (Android) Desarrollar una aplicación para teléfonos con sistema Android que consuma los servicios web desarrollados anteriormente. Este apartado se estima que no se llegará a desarrollar, pero hemos preferido considerar la iteración por si hubiese desvíos importantes en las estimaciones, al utilizar tecnologías y herramientas desconocidas por el alumno. El objetivo de esta iteración sería ampliar los conocimientos del alumno en un sector en auge. El objetivo final del proyecto no es el de tener una aplicación completa y finalizada, como en el proyecto que tomaremos por caso práctico, sino el de demostrar las capacidades del alumno frente al continuo cambio necesario en las aplicaciones web actuales. 1.3. Recursos humanos y personales Este proyecto estará formado por Dan Lucian Adrian como Director del proyecto que tomará todas las decisiones y su dedicación será total. Como tutor Julio Rubio García que tomará las decisiones que estime oportunas. También evaluará parte de la nota final del proyecto y su dedicación al mismo será esporádica. Los miembros del Tribunal formados por un grupo de profesores que evaluarán el proyecto poniéndole la nota final. Su dedicación será la necesaria para leer la memoria y el tiempo dedicado a la defensa del proyecto. 1.4. Plan de comunicación Teniendo en cuenta que se trata de un proyecto que tiene como base el anterior proyecto fin de carrera del alumno del que este tiene un buen conocimiento, las comunicaciones se resumirán en entregas de seguimiento al tutor por parte del alumno que serán por medio del correo electrónico y en el caso de ser necesario se organizarán reuniones con el tutor. Como prevención de la posible pérdida de información cada día se creara un backup de los contenidos del proyecto hasta el momento. 1.5. Dirección de riesgos En este proyecto se han detectado las siguientes posibles fuentes de riesgo: Inexperiencia del desarrollador de la implementación del sistema de gestión de contenido elegido. Trabajo Fin de Grado Página 9 El anterior punto conlleva que las estimaciones de fechas iniciales propuestas por el alumno pueden no ser apropiadas. También afecta el hecho de que el alumno se encuentre trabajando durante el periodo de desarrollo de este proyecto. El diseño propuesto puede acarrear problemas que obligarán a revisar todo lo desarrollado. Problemas por malas instalaciones de las herramientas que se utilizarán. También problemas de hardware que serán limitados por el backup diario que se hace pero aun así este puede llegar a afectar al desarrollo del proyecto si el alumno no dispone de medios para continuar. Riesgo de que el alumno caiga enfermo o de que tenga que viajar fuera del país. Ante la detección de alguna de las fuentes de riesgo antes mencionadas se evaluara su alcance y se replanteará todo lo necesario para poder llevar a cabo el proyecto. Esto incluye dejar sin terminar algunas iteraciones que en un inicio se han propuesto. Como cada fuente de riesgo afecta a ciertos apartados del desarrollo de este proyecto antes de seguir con la siguiente función se evaluará lo realizado hasta el momento para disminuir todo lo posible los riesgos y se corregirá la planificación de las fechas haciendo constar el desvió que dicho riesgo a supuesto. 1.6. Planificación del proyecto Se estimarán las horas y fechas de cada iteración del proyecto definiendo el tiempo necesario para el análisis, diseño e implementación teniendo como base una dedicación semanal de 15 horas. Se definirán los documentos a generar y entregar de cada una de las iteraciones. 1.6.1 Detallar los pasos para cambiar a un proyecto basado en herramientas de gestión de contenido (Iteración 1) 1.6.1.1 Análisis Estimación: 30 horas Periodo: 17/02/2013 – 3/03/2013 1.6.1.2 Diseño Estimación: 15 horas Periodo: 3/03/2013 – 10/03/2013 1.6.1.3 Implementación Estimación: 48 horas Periodo: 10/03/2013 – 2/04/2013 1.6.1.4 Resumen Estimación: 93 horas Periodo: 17/02/2013 – 2/04/2013 1.6.2 Listas de subscripción a las noticias (Iteración 2) 1.6.2.1 Análisis Estimación: 12 horas Trabajo Fin de Grado Página 10 Periodo: 2/04/2013 – 7/04/2013 1.6.2.2 Diseño Estimación: 8 horas Periodo: 7/04/2013 – 10/04/2013 1.6.2.3 Implementación Estimación: 15 horas Periodo: 10/04/2013 – 17/04/2013 1.6.2.4 Resumen Estimación: 35 horas Periodo: 02/04/2013 – 17/04/2013 1.6.3 Proteger el apartado de gestión de la aplicación mediante SSL (Iteración 3) 1.6.3.1 Análisis Estimación: 10 horas Periodo: 2/04/2013 – 5/04/2013 1.6.3.2 Diseño Estimación: 3 horas Periodo: 5/04/2013 – 5/04/2013 1.6.3.3 Implementación Estimación: 3 horas Periodo: 6/04/2013 – 6/04/2013 1.6.3.4 Resumen Estimación: 15 horas Periodo: 02/04/2013 – 6/04/2013 1.6.4 API REST (Iteracion 4) 1.6.4.1 Análisis Estimación: 10 horas Periodo: 17/04/2013 – 25/04/2013 1.6.4.2 Diseño Estimación: 10 horas Periodo: 25/04/2013 – 30/04/2013 1.6.4.3 Implementación Estimación: 25 horas Periodo: 30/04/2013 – 21/05/2013 1.6.4.4 Resumen Estimación: 45 horas Periodo: 17/04/2013 – 21/05/2013 1.6.5 Terminales móviles (Iteración 5) No se hace ninguna estimación ya que no se sabe si se llegará hasta este punto. Trabajo Fin de Grado Página 11 1.6.6 Documentación (Iteración 0) Estimación: 110 horas Periodo: 6/02/2013 – 26/05/2013 1.6.7 Total Estimación: 298 horas Periodo: 6/02/2013 – 26/05/2013 1.7. Listado de entregables ENTREGABLE Plan del proyecto Análisis Iteración 1 Diseño Iteración 1 Implementación Iteración 1 Análisis Iteración 2 Diseño Iteración 2 Implementación Iteración 2 Análisis Iteración 3 Diseño Iteración 3 Implementación Iteración 3 Análisis Iteración 4 Diseño Iteración 4 Implementación Iteración 4 Memoria del proyecto DESCRIPCIÓN Versión de la planificación del proyecto Todo lo referente al análisis de la iteración 1 Todo lo referente al diseño de la iteración 1 Todo lo referente a la implementación de la iteración 1. Todo lo referente al análisis de la iteración 2 Todo lo referente al diseño de la iteración 2 Todo lo referente a la implementación de la iteración 2 Todo lo referente al análisis de la iteración 3 Todo lo referente al diseño de la iteración 3 Todo lo referente a la implementación de la Todo lo referente al análisis de la iteración 4 Todo lo referente al diseño de la iteración 4 Todo lo referente a la implementación de la Memoria del proyecto FORMATO Word Word Word Word Word Word Word Word Word Word Word Word Word PDF 1.8. Revisión del DOP Se hará cada vez que se finaliza una fase del proyecto. 2. Análisis Iteración 1 2.1 Alcance La iteración abarca la conversión y puesta en funcionamiento de la aplicación de gestión de noticias mediante la utilización de Joomla. Trabajo Fin de Grado Página 12 En este documento de análisis y especificaciones se definirán las funcionalidades que debe ofrecer la aplicación. Al tomar como base para el ejemplo la aplicación del proyecto “Gestión documental de las actividades de un Servicio de Comunicación” se intentará dar soporte a un elevado porcentaje de funcionalidades. 2.2 Objetivos El objetivo de este proyecto es pasar la aplicación de origen a una aplicación que tenga como base el CMS Joomla. Mediante el desarrollo de la aplicación se pretende demostrar las grandes facilidades que te ofrece un CMS ya que la mayoría de las funcionalidades que nuestro proyecto de ejemplo tiene las ofrece el CMS Joomla. 2.3 Entregables - Una aplicación web que permite gestionar las noticias de una forma similar a la antigua aplicación. Documento de Análisis y Especificaciones. Documento de Diseño Técnico. Código de la aplicación Web. 2.4 Aprendizaje He considerado oportuno este apartado ya que afecta a toda la Iteracion1 y en él se justificaran las modificaciones que aparecen con respecto a lo planteado en el DOP. Tras un periodo de aprendizaje del CMS Joomla se deciden las modificaciones especificadas debajo con respecto a algunos de los puntos de esta iteración. Con respecto al punto de analizar y detallar los pasos necesarios para replicar la BD del antiguo proyecto se ha llegado a la conclusión de que no es necesario realizar dicha replica. El motivo de la decisión es que Joomla es una herramienta que te permite hacer un nivel de abstracción mayor sin tener que llegar hasta las BD. Solamente te tendrás que encargar de cómo deseas que funcione tu aplicación y qué es lo que deseas que se pueda hacer con ella y por debajo ya estarán creadas las tablas necesarias para dicho proceso. A la hora de detallar los pasos de acciones al nuevo sistema es tan básico que no es necesario explicarlo en detalle. A veces se limitará a habilitar funcionalidades existentes desde el backend de la aplicación y a veces instalar plugins existentes que te ofrecen las funcionalidades buscadas. Tras la investigación hecha sobre los plugins necesarios para la aplicación se ha llegado a la conclusión, que para toda funcionalidad que se implementará existen plugins que ofrecen dicho funcionamiento. Por lo tanto el proceso de creación de plugins no se detallara. De lo explicado más arriba se llega a la conclusión de que muchos puntos a tratar en la primera iteración no tienen sentido en un sistema CMS Joomla salvo que se desean realizar cosas muy especiales pero no es nuestro caso. Trabajo Fin de Grado Página 13 Como conclusión en este punto cambiaremos el detallar la forma de pasar las funcionalidades a detallar las funcionalidades que ofrecerá la aplicación. 2.5 Descripción 2.5.1 Definiciones Frontend: la parte publica de la aplicación que será visible para todo el mundo y que tendrá un apartado de login mediante el cual se mostrarán más opciones para los usuarios. Backend: la parte privada de la aplicación a la cual solamente tendrá acceso el administrador. CMS o Joomla: Sistema de gestión de contenido. Se hace esta equivalencia solamente para este proyecto ya que Joomla es un CMS en sí. 2.5.2 Seguridad Toda funcionalidad de la aplicación que requiera de la inserción de datos implica una validación interna de dichos datos para que así se limiten los posibles ataques. En caso de que los datos introducidos no sean válidos aparecerán mensajes de error suficientemente descriptivos del problema, para que el usuario pueda hacer las modificaciones oportunas. En caso de error de alguna de las funcionalidades de la aplicación ésta nunca devolverá errores descriptivos que pueden ser aprovechados por atacantes para entender el funcionamiento interno de la aplicación y propiciar futuros ataques. Este aspecto de validación de datos está contemplado por el CMS Joomla al saltarse cualquier carácter extraño que pueda dañar la aplicación. 2.5.3 Funcionalidades de la aplicación La presentación de las distintas funciones recogidas puede variar respecto a las mismas funciones que se daban en la aplicación de origen. Estos cambios afectaran tanto a las funciones de backend como las de frontend. Con objetivo de tener separadas las funcionalidades que se dan en el frontend/backend a cada funcionalidad que aparece a continuación se le concatenarán la palabra correspondiente a la interfaz en la que se ofrece. 2.5.3.1 Inicio de Sesión – frontend/backend La aplicación permitirá al usuario iniciar sesión mediante usuario/contraseña y comprobará la validez de dichos datos contra los guardados en la BD del CMS. La gestión de tipos de usuarios será delegada en el propio sistema CMS empleado. Nosotros solamente nos encargaremos de la correcta asignación de los permisos que éstos tienen. 2.5.3.1.1 Recordar contraseña/usuario Existirá la posibilidad de recordar la contraseña y el usuario del cliente mediante una validación por correo electrónico. Trabajo Fin de Grado Página 14 2.5.3.2 Inicio – frontend Al acceder a la aplicación se cargará una página de inicio que mostrará un listado de noticias. Dicho listado contendrá las noticias ordenadas por fechas, apareciendo primero las noticias más recientes y siguiendo hasta la última noticia. Para disminuir la carga de la web se paginarán las noticias, siendo el número de noticias que se mostrará en cada página marcado por el administrador desde el backend. En el listado de noticias se mostrarán datos reducidos de cada noticia siendo posible ver toda la noticia mediante un enlace que aparecerá debajo de cada una de las noticias. Si se pulsa sobre el título de la noticia se le llevara a un apartado donde podrá dejar comentarios y valoraciones sobre las noticias. El apartado de comentarios solamente estará disponible para usuarios registrados. 2.5.3.3 Registrar – frontend Permite registrar usuarios que tendrán acceso a funcionalidades predefinidas en el backend por el administrador. Para el registro de usuario se pedirán el nombre, apellido, dirección de correo electrónico, sexo, imagen del avatar, una pequeña descripción del usuario y una contraseña. De los datos que se piden en el registro solo algunos serán obligatorios. 2.5.3.4 Filtrara noticias – frontend Habrá dos formas de filtrar las noticias una será por mes y la otra por palabras insertadas. Para ello se creara un listado de los meses y el número de noticias que hubo en ese mes y dicho listado se mostrará en la parte derecha de la aplicación justo debajo del módulo de acceso a la aplicación. Para el filtrado por palabras se utilizará un input arriba en la aplicación que permitirá filtrar las noticias por las palabras que se inserten en el. Este filtrado de noticias buscará la palabra en todos los campos que puede tener una noticia salvo que se marque que por dicho campo no se puede buscar desde el backend. 2.5.3.5 Iniciar Sesión – frontend Cualquier usuario registrado y aprobado por el administrador podrá iniciar sesión en la aplicación para acceder a una serie de funcionalidades avanzadas. Dicho inicio de sesión se podrá hacer en cualquier página de la aplicación mediante un pequeño formulario de usuario/contraseña en la parte derecha de la aplicación. 2.5.3.6 Publicar noticias – frontend autenticado Una vez iniciada sesión los usuarios podrán publicar Artículos que para su publicación tendrán que ser aceptados por el administrador o bien el usuario tendrá que pertenecer a un grupo que tenga permisos de publicación. Al publicar artículos tendrán que completar como mínimo el título, un pequeño resumen y toda la noticia. Además de los campos obligatorios se pueden agregar ficheros de audio, vídeo o documentos a la noticia y se podrá marcar si el artículo se publicara o no en función del permiso del usuario. Trabajo Fin de Grado Página 15 2.5.3.7 Editar noticias – frontend autenticado Una vez iniciada sesión los usuarios podrán editar las noticias que hayan publicado con antelación. 2.5.3.8 Visualizar noticias – frontend Al acceder a la web se mostrará el listado de noticias actuales ordenadas por fecha. Al hacer click en cada noticia se accederá al detalle de esta. Por defecto las noticias que tengan ficheros de audio y vídeo mostrarán dichos contenidos en un reproductor en el listado mencionado. 2.5.3.9 Descargar noticia - frontend Toda noticia que tenga un fichero adjunto tendrá un link mediante el cual el usuario podrá descargar el fichero de la noticia en su equipo. Dicho link solamente aparecerá al acceder al detalle de la noticia. 2.5.3.10 Menús – frontend La aplicación tendrá dos menús en la parte pública, uno que tendrá los elementos por los que puede navegar un usuario sin acceso y otro al que solamente tendrán acceso los usuarios registrados. 2.5.3.10.1 Menú principal Estará situado en la parte de arriba de la aplicación y contendrá un enlace a la página principal de la web y otro menú desplegable que contendrá un enlace a cada una de las categorías de la aplicación y se encargará de mostrar las noticias de dicha categoría. 2.5.3.10.2 Menú de Usuarios Este menú aparecerá en la posición del módulo de acceso a la aplicación sustituyendo dicho módulo una vez iniciada la sesión por un usuario. Este menú contendrá las siguientes opciones: Creación de artículos. Listado de todos tus artículos publicados. Editar tu perfil. Moderar comentarios – cambiar los comentarios que has creado para las noticias. Alertas - apartado de configuración mencionado anteriormente. 2.6 Documentación de referencia y anexos Para el desarrollo de esta parte de la aplicación será necesario estudiar los apartados de instalación y funcionamiento del CMS Joomla. Para necesidades específicas será necesario estudiar plugin que pueden ofrecer las funcionalidades que se desean. En el caso de que no se consiga encontrar ningún complemento del CMS Joomla que cumpla con los requisitos de la aplicación se tendrá que estudiar la forma de crear uno personalizado o modificar uno existente. Trabajo Fin de Grado Página 16 3. Diseño Iteración 1 Apartado en el cual se detallarán los pasos a llevar a cabo para la implantación de una instalación básica de Joomla sobre la cual se añadirán todos los apartados especificados en el análisis. 3.1 Instalación Para la instalación necesitamos de un servidor web y para ello utilizaremos la herramienta Xampp que ofrece un servidor web apache gratuito disponible para Windows. Para la instalación copiaremos los ficheros de Joomla en la ruta “C:\xampp\htdocs” ruta en la que por defecto se instala Xampp. Tras arrancar el servidor accedemos a “localhost” en el navegador y seguiremos los pasos del asistente de instalación de Joomla que aparece. Cuando se nos pide BD y usuarios utilizaremos los datos que aparecen debajo y como contraseña de usuario administrador pondremos “111111Aa”. Datos de la instalación: Datos de la BD BD: qpv314 Usuario: qpv312 Host: qpv314.dantodo.com Contraseña: 111111Aa 3.2 Funcionalidades Para la implementación de gran parte de las funcionalidades de la aplicación se utilizará el plugin k2 que ofrece más posibilidades de gestión de noticias/usuarios que el propio Joomla. Esta decisión se ha tomado por las siguientes limitaciones que ofrece Joomla y que se consiguen mediante la utilización del plugin k2. Limitaciones: Asignar un artículo a varias categorías. Agregar campos adicionales a las noticias. Gestionar mejor los usuarios mediante grupos personalizados. Enlazar contenido multimedia desde multitud de páginas como youtube.com. Estas son las limitaciones que cubre k2 y que en nuestro proyecto solo con Joomla no nos es suficiente. 3.2.1 Inicio de sesión Todo usuario previamente registrado en el sistema dispondrá de un nombre de usuario y contraseña para acceder a su parte privada de la aplicación. El acceso a la aplicación se hará mediante un formulario que se encargara de comprobar que el usuario este en la BD de la aplicación y que no se encuentra bloqueado. Trabajo Fin de Grado Página 17 Este funcionamiento es válido tanto para el frontend como para el backend. Para tener la funcionalidad de acceso a la aplicación hay que habilitarla desde el apartado de módulos creando un nuevo módulo de tipo “K2 user”, con nombre “K2 user” que se situará en el menú de la parte derecha de la aplicación. En el mismo módulo ya aparecen las opciones de “recordatorio de contraseña”, “recordatorio de usuario” y la opción de “crear una nueva cuenta”. 3.2.2 Registrar Para que los usuarios nuevos que se registren tengan acceso a la hora de crear artículos y comentarios se tendrán que crear nuevos grupos k2 desde el backend de Joomla. Se crearán 3 grupos y cada uno tendrá los permisos indicados a continuación: Administradores: todos los permisos. Autores: todos los permisos menos los de edición de artículos que no son del usuario. Registrados: todos los permisos menos los de publicación y edición de artículos que no son del usuario. Tras crear los grupos se modifican las configuraciones de K2 para que los usuarios por defecto se den de alta como pertenecientes al grupo de Registrados. Para que aparezca la opción de registrar se tiene que habilitar desde el apartado de Gestión de Usuarios de las configuraciones de Joomla. Para evitar ataques mediante robots se utilizará un campo captcha que se activará desde el apartado de configuración genérica del gestor de contenido k2. Para funcionar es necesario registrarse en google.com/recaptcha y obtener unas claves pública/privada mediante las cuales se accede al servicio. Dichas claves se tendrán que poner en el apartado antes mencionado. 3.2.3 Finalizar sesión Al pulsar sobre el botón de finalizar sesión se tiene que salir de la aplicación como usuario registrado y redirigir a la página de inicio de la aplicación. Para ello en las opciones del módulo creado para el acceso se tiene que marcar que la página de redirección de salida sea la de inicio de la aplicación. 3.2.4 Página de Inicio La página de inicio tendrá un listado de los artículos de la aplicación ordenados decrecientemente. Para hacer el funcionamiento se creará un enlace que mostrará todas las noticias de una categoría. Como no todos los artículos pertenecen a todas las categorías entonces se crea una categoría genérica llamada “Global” a la que se asignarán por defecto los artículos, y se utilizará dicha categoría para mostrar el listado. Trabajo Fin de Grado Página 18 Para que el orden sea decreciente se marcará desde las opciones del listado de categoría y se marcará que se ordene por la fecha de modificación para que si el artículo sufre modificaciones sea visible en la página de inicio entre los primeros. También se definirá que solamente se muestren los últimos 5 artículos desde el propio apartado de configuración. 3.2.5 Filtrar noticias En la parte superior derecha de la aplicación aparecerá un cuadro que permitirá buscar noticias por palabras y se buscará la palabra introducida en todos los campos que contempla la creación de un artículo. Para ello se creará un módulo de tipo búsqueda k2 que se situará en dicha posición. Dicho módulo mostrará todos los artículos de la aplicación que tengan dicha palabra o palabras en alguno de sus campos. Se creará otro filtro para la aplicación que mostrará un listado de los meses y los artículos que se han creado en dichos meses. Para ello se creara un nuevo módulo “k2 Tools” con el nombre de “Calendario de Noticias” que se situará debajo del módulo de login de la aplicación. 3.2.6 Publicar noticias Para que la opción de creación de artículos aparezca será suficiente que el usuario esté asignado a un grupo que tenga permisos de creación de artículos ya que el módulo “k2 user” se encargará de mostrarle dicha opción. 3.2.6.1 Información adicional Al no ser suficiente con los campos que nos ofrece la creación de un artículo en Joomla crearemos nuevos campos necesarios en los artículos. Los nuevos campos se llamarán valoración y temas. El objetivo no es replicar todos los campos de la antigua aplicación sino mostrar cómo se puede hacer mediante la utilización del “plugin k2”. Para ello crearemos un nuevo Grupo de “Campos Extra” que se llamará “Información Adicional” y luego crearemos dos Campos asociados al grupo así definido. Los campos se llamarán valoración y temas y serán del tipo “combobox” y tendrán unos valores predefinidos. Por defecto serán públicos y no obligatorios. Con cualquier nuevo campo que se necesite a la hora de crear un artículo se seguirán los mismos pasos. Para que se visualicen en la sección de creación de artículos se tienen que seleccionar el grupo de campos extra en las propiedades de cada categoría creada. Para publicar las noticias se crearán 4 categorías que englobaran todas las noticias de la aplicación: TV: noticias que contienen incrustados archivos de vídeos y que normalmente aparecen por televisión antes. Radio: noticias que contienen incrustados archivos de audio y que normalmente se escuchan por la radio antes. Internet: noticias que se recopilan desde internet y son de interés para la aplicación. Trabajo Fin de Grado Página 19 Global: categoría que será asignada por defecto a toda noticia dada de alta en la aplicación. 3.2.7 Editar noticias Para la edición de noticias será suficiente con asignar el usuario a un grupo que tenga permisos de edición de noticias. En nuestro caso por defecto un nuevo usuario se asocia al grupo “Registrados”. Conforme a lo explicado anteriormente dicho grupo ya tiene permisos de edición de artículos, solo de los personales de cada usuario. Por lo tanto como el grupo ya tiene dichos permisos el usuario los hereda. 3.2.8 Eliminar noticia La funcionalidad de eliminar noticia será asignada por defecto a los usuarios que pertenecen al grupo de Autores; solamente podrán eliminar las noticias publicadas por ellos. Para ello al darse de alta como usuario registrado se asignarán al grupo Registrados y posteriormente el administrador debe asignarlos al grupo de autores desde el backend de la aplicación. 3.2.9 Descargar noticia - frontend El propio módulo de k2 de creación de noticias permite agregar ficheros adjuntos a la noticia y permite descargarlos una vez publicada la noticia y accediendo a los detalles de la misma, así que este apartado estará solucionado con habilitar la creación de artículos para el usuario. 4. Implementación Iteración 1 En este apartado de la documentación se entrega la aplicación en un fichero Zip y se detallarán los cambios que se han tenido que hacer a los plugins de Joomla o al proprio Joomla para que se consiga el funcionamiento deseado de la aplicación. 4.1 Idiomas Al instalar la aplicación en español hay que tener en cuenta que no todos los plugins que se utilizan vienen con traducciones de español. Para adaptar los plugins al español se han seguido los pasos explicados a continuación basándonos en el concepto de plugin de Joomla, aquel de que cada plugin tiene que tener definidos ficheros con traducciones utilizadas en la interfaz del plugin. Una vez entendido el concepto lo que se hace es replica el fichero de traducciones origina con su formato y se cambian las traducciones al idioma deseado. Por lo tanto se copia el fichero original y se modificado tanto su nombre como las traducciones que contiene. Para encontrar los ficheros que contienen las traducciones originales de los plugins se buscan en dos rutas que corresponden cada una al apartado backend y frontend de la aplicación. Si solo se desea cambiar el idioma del plugin en el frontend solamente se modificará el fichero correspondiente. Rutas de los ficheros de traducciones de los plugins: [ruta_base]\administrator\language – ficheros de idiomas de backend. Trabajo Fin de Grado Página 20 [ruta_base]\language – ficheros de idiomas de frontend. Una vez encontrado lo que se desea cambiar se accede a la ruta correspondiente y de allí a la carpeta del idioma original y se busca el fichero del idioma del plugin. Tras encontrarlo se copia en la carpeta del idioma de destino y se le cambia el nombre para que tenga el formato del idioma de destino y se cambian las traducciones internamente. A partir de aquí es el propio Joomla el que se encarga de recoger las traducciones correctas en función del idioma de la aplicación. Estas modificaciones se han realizado para el plugin de múltiples categorías del módulo k2. 4.2 Múltiples categorías Al instalar el plugin adicional de múltiples categorías del módulo k2 el funcionamiento que se da a la hora de crear un nuevo artículo no es el deseado ya que se nos permite seleccionar desde la misma ventana dos veces la misma categoría. La primera vez para seleccionar la categoría del artículo y la segunda vez en el listado de categorías desde la cual se pueden asignar más de una al mismo artículo. Para evitar dicho comportamiento se modifica el código para que en el combo solamente aparezca la categoría “Global” y en el listado de categorías a seleccionar aparezcan todas las demás menos la de “Global”. Para ello modificamos el funcionamiento tanto en el backend como en el frontend de la aplicación. Se modifica el código de los ficheros de debajo para que en el combo de creación de artículos solamente aparezca la categoría “Global”. Para ello se elimina todas las demás categorías del dato que contiene las categorías. Ficheros modificados: Backend: [ruta_base]\ administrator\components\com_k2\views\item\tmpl\default.php Frontend: [ruta_base]\ components\com_k2\templates\default\itemform.php Para eliminar la categoría del listado de categorías adicionales se modifica el código del fichero de debajo; solamente se trata de un fichero ya que es código compartido tanto por el backend como por frontend. Fichero: [ruta_base]\ plugins\k2\k2additonalcategories\k2additonalcategories.php 5. Análisis Iteración 2 5.1 Alcance La iteración contempla la implementación de los avisos en la aplicación como una opción más en el menú de los usuarios registrados. Trabajo Fin de Grado Página 21 5.2 Objetivos El objetivo de esta iteración es la de permitir a los usuarios registrados estar al tanto de las noticias que les interesen sin tener que revisar cada día el contenido nuevo que se halla agregado. 5.3 Entregables - La aplicación web de la iteracion1 con el nuevo funcionamiento agregado. Documento de Análisis. Documento de Diseño Técnico. Código de la aplicación Web de la iteracion1 ampliado con las funcionalidades de la iteracion2. 5.4 Descripción Se crearán alertas a las que los usuarios podrán subscribirse y que podrán configurar. Las alertas se podrán configurar para que se avise cada cierto intervalo de tiempo y para que se avise al usuario solamente si hay noticias en las categorías que ha preseleccionado al subscribirse a la alerta. Tanto los intervalos de tiempo como las categorías que el usuario registrado podrá seleccionar se podrán configurar; por defecto toda categoría dada de alta en la aplicación será incluida en el listado de preselección de alertas. En un inicio se crearán intervalos de tiempo diario, semanal, quincenal, mensual, pero en cualquier momento se podrán crear otros. 6. Diseño e implementación Iteración 2 Se agrupan en un solo paso las dos tareas ya que en realidad se trata de un trabajo de investigación para ver que plugin se amolda más a lo que buscamos y la implementación del mismo en la aplicación. Al investigar los plugins existentes para el CMS Joomla que traten el tema que nos interesa descubrimos que hay muchos plugins que realizan lo que se desea hacer en la aplicación. El que seleccionamos para la aplicación es “J!MailAlerts” ya que nos da toda la funcionalidad que buscamos y a diferencia de otros es un plugin gratuito. Al estar limitados por la utilización del plugin k2 a buscar solamente los que son compatibles entonces hay que instalar una extensión (J!MailAlerts - K2 - Latest Items) que permite hacer la compatibilidad entre los dos plugins y que nos da la posibilidad de creación de alertas que cumplen los criterios del análisis. Tras la instalación del plugin hay que crear un menú de usuario que tenemos que asociar al módulo de acceso de k2 para que así nos aparezca igual que las demás opciones que dicho módulo ofrece. Trabajo Fin de Grado Página 22 Esta opción nos llevará a un listado de las alertas previamente creadas y configuradas y permitirá al usuario el alta/baja de las mismas y su configuración también. Como se explica en el apartado de implementación de la primera implementación para este módulo también hay que configurar su correspondiente fichero de idioma para que así muestre los textos en español. 7. Análisis Iteración 3 7.1 Alcance La iteración contempla la habilitación del SSL en la aplicación utilizando certificados personales existentes o creados utilizando los conocimientos adquiridos en la asignatura de Seguridad de la titulación. 7.2 Proteger el apartado de gestión de la aplicación mediante SSL Como para el desarrollo del proyecto utilizamos la herramienta gratuita de xampp que viene configurada con todos los requisitos necesarios vamos a explicar los pasos necesarios que se harían para que funcione el SSL en nuestro sitio. Para activar el sitio seguro se configurará apache para que responda en el puerto 443. Para ello se modificará el fichero httpd.conf. En nuestro caso xampp tiene ficheros de configuración separados por cada módulo que puedes agregar haciendo las modificaciones más fáciles de encontrar. Para el módulo de SSL tiene un fichero de configuración separado httpd-ssl.conf. Una vez hecho esto también hay que definir un “virtual host” relacionado al puerto 443. Dicho “virtual host” hay que definirlo en el mismo fichero mencionado antes. El “virtual host” tendrá definidos los certificados que se utilizarán para la autenticidad del servidor el nombre al que responde, la ruta básica de donde espera cargar el sitio. Por último para que apache detecte que se desea cargar la configuración SSL se tiene que arrancar el servidor con el módulo “ssl_module”, de esta forma se tienen en cuenta todas las configuraciones mencionadas antes. 7.2.1 Configuración personal Como el proyecto persigue configurar el SSL con un certificado personalizado entonces tenemos que generar uno y sustituir los ya existentes por ellos. Para configurar el servidor con el certificado que nosotros deseamos hay que generar primero el certificado Esto se puede hacer con las herramientas que se han utilizado en la asignatura de Seguridad. Para ello necesitamos un certificado de tipo “SSL Server” y su clave para el servidor y el fichero “.key” con la clave del certificado. Se definen las variables SSLCertificateFile y SSLCertificateKeyFile en el “virtual host” definido antes que apunten a las rutas de donde se encuentra los ficheros del certificado y el de la clave. Trabajo Fin de Grado Página 23 Hay que tener en cuenta que cualquier “virtual host” que creemos de ahora en adelante para el proyecto tendremos que crear su correspondiente “virtual host” en el fichero de SSL. 8. Análisis Iteración 4 En esta iteración se creara una API que ofrezca acceso a funcionalidades de la aplicación. Se ha decidido por un API REST ya que se desea enviar el mínimo contenido en una comunicación cliente-servidor y en caso de otra alternativa como es un API SOAP se envían más datos ya que se envía un documento XML tanto para la petición como para la respuesta. 8.1 Alcance La iteración abarca la creación de un API REST que servirá para que otros dispositivos puedan crear aplicaciones basándose en los datos que hay en la aplicación. El objetivo general es dar la posibilidad a clientes a implementar aplicaciones que utilicen los recursos de la web desarrollada en el proyecto detallado en las iteraciones anteriores. 8.2 Objetivos Se considerará conseguido el objetivo si se entregan una serie de métodos de acceso a funcionalidades de la aplicación que respeten el formato de llamadas explicadas en el Anexo I sobre información de una API REST. 8.3 Perspectiva general de la solución Se creará un listado de llamadas que realizarán funciones básicas que se pueden realizar desde la aplicación web. Aunque sean funcionalidades básicas a implementar hay que ser conscientes de que las funcionalidades que se describan y los métodos o funciones que se expongan, deben estar pensadas para ser reutilizadas en funcionalidades similares o extendidas, para hacer posible un futuro crecimiento de esta plataforma. A modo de resumen, las opciones con las que se contará en esta primera versión serán las siguientes: - Listado de noticias, categorías, alertas. - Filtrado de noticias buscando por usuario, categoría, título de noticia. - Detalle de noticia. - Alta/baja de las listas de suscripción (alertas). 8.4 Seguridad, Fiabilidad y Disponibilidad Se prevén las siguientes restricciones de seguridad: - Todas las comunicaciones serán mediante HTTPS. Trabajo Fin de Grado Página 24 - Las funciones desarrolladas nunca devolverán id reales de datos de la BBDD, sino un alias (ClientRef o token) diferente para cada id distinto. - Los Servicios Web expuestos, que requieran de autenticación, nunca devolverán información de clientes que no correspondan exactamente al Cliente vinculado con la petición. - Se realizará siempre una comprobación que verifique que el Cliente es un usuario existente en BD, posibles bajas etc. - Debe quedar registrada cualquier operación realizada desde los dispositivos que hacen uso de la API. - Como se trata de funcionalidades que tienen como objetivo ser utilizadas por terceros cada datos de entrada sera validado para que respete el formato de datos esperado. Con respecto a la fiabilidad y disponibilidad, esta aplicación requiere de una arquitectura capaz de ofrecer servicio en alta disponibilidad, ya que se trata de una herramienta de cliente. 8.5 Funcionalidades de la aplicación. 8.5.1 Listado de Noticias Una llamada a este método permite al cliente obtener un listado ordenado por fecha de publicación de las noticias publicadas de la aplicación. Los datos que se mostrarán por cada noticia serán el título y la fecha de publicación, la categoría, y el resumen de la noticia, así como también el usuario que creó dicho artículo. Para evitar cargas extremas al servidor se implementará un sistema de paginado que ofrezca la posibilidad de obtener noticias por páginas. 8.5.2 Listado de Categorías Una llamada a este método permite al cliente obtener un listado ordenado por nombre de categoría de las categorías publicadas en la aplicación para el usuario invitado. Los datos que se mostrarán por cada categoría serán el título y el número de elementos a los que está asociada la categoría. 8.5.3 Listado de Alertas Una llamada a este método permite al cliente obtener un listado ordenado por nombre de alertas de las categorías publicadas en la aplicación para el usuario pasado. Los datos que se mostrarán por cada alerta serán el título y una pequeña descripción de la alerta. A esta funcionalidad solamente tendrán acceso usuarios registrados así que se hará una previa validación de los datos antes de devolver el resultado. Trabajo Fin de Grado Página 25 8.5.4 Filtrado de Noticias Una llamada a este método se encargará de devolver un listado de noticias que cumpla con los criterios de búsqueda. De momento solamente se permitirá buscar noticias publicadas por un usuario en concreto, noticias que pertenezcan a una categoría en concreto o noticias que contengan ciertas palabras en su título. 8.5.5 Detalle de noticia Se mostrará el detalle de una noticia pasada que además de los datos que ya se devolvían en el listado ofrecerán los siguientes datos: Tema. Valoración. Las demás categorías a las que pertenece. El texto completo de la noticia. Como ya se detalló en este apartado se eliminará cualquier archivo adjunto a la noticia y solamente se mostraran los textos que la acompañan. 8.5.6 Alta de las listas de suscripción (alertas) Funcionalidad que ofrece la posibilidad de asociar al usuario pasado la alerta seleccionada, antes de hacer cualquier cambio se validarán todos los datos y que el usuario existe y es válido. Si el usuario ya tiene otras alertas asociadas se da de baja de dichas listas de suscripción y se le da de alta en la nueva. 8.5.7 Baja de las listas de suscripción (alertas) Funcionalidad que ofrece la posibilidad de desasociar al usuario de cualquier lista de suscripción a la que pertenezca. 9. Diseño Iteración 4 Toda la documentación del diseño técnico de la iteración 4 estará orientada a ser utilizada por aplicaciones móviles de terceros. 9.1 Objeto del documento El objetivo de este documento es detallar el funcionamiento del API que se expondrá para aplicaciónes móviles de terceros. En él aparecerán los diferentes métodos que compondrán el API, así como los parámetros y formato de los parámetros de entrada y salida. 9.2 Definiciones, acrónimos y abreviaturas clientRef: Identificador único que definirá a cada uno de los clientes que podrán llamar a la aplicación. clientRef = RC4 (<login>&<pass>) Trabajo Fin de Grado Página 26 noticiaRef: Identificador que referencia una noticia de la aplicación. Se formará de la siguiente forma: noticiaRef = RC4 (<ID noticia>) alertaRef: Identificador que referencia una alerta de la aplicación. Se formará de la siguiente forma: alertasRef = RC4 (<ID alerta>) categoriaRef: Identificador que referencia un identificador de una categoría de la aplicación. Se formará de la siguiente forma: categoriaRef = RC4 (<ID categoria>) 9.3 API En este apartado se detallará el WebService que se utilizará para la comunicación entre las aplicaciones de terceros para terminales móviles y los sistemas técnicos. Los diferentes puntos que se tratarán son: - Sitio web de la API. - Parámetros de entrada comunes. - Formato de llamada. - Formato de la respuesta JSON. - Métodos expuestos en la API. - Aspectos de seguridad. 9.4 Sitio web de la API 9.4.1 Entorno desarrollo/producción En nuestro caso como se trata de una aplicación desarrollada por el alumno para el Trabajo Fin de Grado tanto el entorno de desarrollo como el de producción serán los mismos. Para ello el alumno se dará de alta una entrada DNS en la Web no-ip.info que apuntará al servicio web que tendrá levantado para las pruebas. Dicho servicio estará levantado en casa del alumno por las limitaciones que se tienen a la hora de hacer pruebas con certificados personales en hostings de prueba. URL https://apirest.proyecto.danlucian.no-ip.info/ 9.5 Parámetros de entrada comunes Todas las llamadas a métodos del WebService que requieran de autenticación, tendrán tres parámetros comunes: Trabajo Fin de Grado Página 27 - accessKeyId: identificador del usuario o token que realiza la petición. Será el parámetro clientRef , codificado en base64. Ejemplo: "ABCDEF123456" Codificado en Base 64: " QUJDREVGMTIzNDU2 " - timestamp: marca de tiempo de la petición. Fecha y hora en formato GMT (Greenwich Mean Time) del momento de realizar la petición, en el siguiente formato: aaaa-mm-ddThh:mm:ss Ejemplo: 2010-07-02T09:11:58 La petición no será válida, y devolverá un código de error, si la fecha y hora indicadas difieren en más de 15 minutos con la fecha y hora del servidor. - signature: firma de la petición para comprobar la autenticidad de la misma. Se forma mediante la codificación SHA1 (hexadecimal) de la cadena formada resultado de la concatenación de: - El hash MD5 (hexadecimal) del parámetro ClientRef El nombre de la función u operación a realizar. La marca de tiempo (timestamp) de la petición. Podría por tanto expresarse como: SHA1(MD5(<ClientRef>)<NombreFuncion><Timestamp>) 9.6 Formato de llamada En este apartado se define el formato en el que deben enviarse los parámetros de llamada a los diferentes métodos de la API. Todos los métodos, independientemente de que sean POST, GET, PUT, DELETE, recibirán un único parámetro llamado param que se formará de la siguiente manera: Codificar en UTF-8 los parámetros de cada uno de los métodos, según se especifica más adelante en este documento. Se conformará un string en formato JSON con los parámetros anteriormente codificados. Se aplicará una codificación RC4 al string anterior, utilizando la clave ‘proyecto.danlucian’. Se codificará en base64 el string anterior. Formato: $param = base64(rc4(json(utf-8(<parámetros de entrada>)))) NOTA: en la recepción hay que hacer el proceso inverso Trabajo Fin de Grado Página 28 Ejemplo de llamada GET: https://apirest.proyecto.danlucian.no-ip.info/v1/noticias?param=$param Ejemplo de llamada POST: https://apirest.proyecto.danlucian.no-ip.info/v1/alerta POST $param Ejemplo de llamada DELETE: https://apirest.proyecto.danlucian.no-ip.info/v1/alerta DELETE $param Ejemplo de llamada PUT: https://apirest.proyecto.danlucian.no-ip.info/v1/alerta PUT $param 9.7 Formato de respuesta Con el fin de estandarizar la respuesta de los métodos expuestos en el WebService, se seguirá la siguiente estructura en cualquier JSON de respuesta: {"status":"$status","code":"$code","description":"$description", "data":"$data"} -$status: 1 => la operación se ha realizado con éxito. 0 => ha habido algún error en la operación. - $code: en caso de éxito, este campo vendrá vacío. En caso de error, este campo contendrá un código numérico que identificará de manera unívoca el error que se ha producido en la operación. - $description: campo opcional que contendrá una descripción del resultado de la operación. - $data: en caso de error, este campo vendrá vacío. En caso de éxito, este campo contendrá la información específica del método que ha sido llamado. Para más detalle sobre este campo, hay que consultar el método en cuestión dentro de este documento. 9.8 Métodos del API 9.8.1 Listado de noticias Esta función será la base de presentación aplicaciones de terceros, y debe construirse opciones y contenido sin comprometer su versiones posteriores, salvo en cambios funcionamiento de esta versión). de información desde la aplicación hacia las de forma que se garantice su crecimiento en flexibilidad ni compatibilidad hacia atrás (las muy importantes, no deberían alterar el Mostrará el listado de noticias de la aplicación. Trabajo Fin de Grado Página 29 URL https://apirest.proyecto.danlucian.no-ip.info/v1/noticias Método GET Nombre de método para el parámetro signature noticelist 9.8.1.1 Parámetros de entrada - top (opcional): indica el número total de registros a devolver. Este parámetro se utilizará para la paginación de los resultados. - min (opcional): indica el identificador a partir del cual se deben devolver los resultados. Este parámetro se utilizará en combinación con el anterior para la paginación de los resultados. El valor de este parámetro será el número a partir de cual se empezara a paginar la respuesta. 9.8.1.2 Parámetros de salida Se entiende que estos son los parámetros del campo data. - numTotal: número total de noticias. Este dato se devuelve para utilizarlo en la paginación. Por cada noticia o ítem se devolverá la siguiente información: - noticiaRef: identificador de la noticia. - categoriaRef: identificador de la categoría de la noticia. - Título: descripción de la noticia. Pequeño resumen de la noticia que aparece en el frontend de la aplicación también. - usuario: nombre del usuario que creo el artículo. 9.8.2 Listado de Categorías Método que devuelve el listado de categorías públicas de la aplicación. URL https://apirest.proyecto.danlucian.no-ip.info/v1/categorias Método GET Nombre de método para el parámetro signature categoriaslist 9.8.2.1 Parámetros de entrada No necesita de ningún parámetro de entrada extra; una simple llamada a dicha URL devolverá las categorías. 9.8.2.2 Parámetros de salida Se entiende que estos son los parámetros del campo data. - numTotal: número total de categorías. Trabajo Fin de Grado Página 30 Por cada categoría o ítem se devolverá la siguiente información: - categoriaRef: identificador de la categoría. - Título: Nombre de la categoría. - Descripción: Pequeño resumen de la categoría. 9.8.3 Listado de Alertas Método que devuelve el listado de alertas disponibles de la aplicación. URL https://apirest.proyecto.danlucian.no-ip.info/v1/alertas Método GET Nombre de método para el parámetro signature alertaslist 9.8.3.1 Parámetros de entrada - clientRef: identificador único de usuario. 9.8.3.2 Parámetros de salida Se entiende que estos son los parámetros del campo data. - numTotal: número total de alertas. Por cada alerta o ítem se devolverá la siguiente información: - alertaRef: identificador de la alerta. - Título: Nombre de la alerta. - Descripción: Pequeña descripción de la alerta. 9.8.4 Filtrado de noticias Método que devuelve el listado de las noticias que cumple el filtro aplicado. URL https://apirest.proyecto.danlucian.no-ip.info/v1/noticias/filtro Método GET Nombre de método para el parámetro signature noticiasfilter 9.8.4.1 Parámetros de entrada - usuario (opcional): nombre del usuario que publicó la noticia. - categoría (opcional): nombre de la categoría a buscar. - titulo (opcional): palabra/s que se buscara en el título de las noticias. Trabajo Fin de Grado Página 31 - top (opcional): indica el número total de registros a devolver. Este parámetro se utilizará para la paginación de los resultados. - min (opcional): indica el identificador a partir del cual se deben devolver los resultados. Este parámetro se utilizará en combinación con el anterior para la paginación de los resultados. El valor de este parámetro será el número a partir de cual se empezará a paginar la respuesta. 9.8.4.2 Parámetros de salida Se entiende que estos son los parámetros del campo data. - numTotal: número total de noticias. Este dato se devuelve para utilizarlo en la paginación. Por cada noticia o ítem se devolverá la siguiente información: - noticiaRef: identificador de la noticia. - categoriaRef: identificador de la categoría de la noticia. - Título: descripción de la noticia. Pequeño resumen de la noticia que aparece en el frontend de la aplicación también. - usuario: nombre del usuario que creo el artículo. 9.8.5 Detalle de noticia Método que devuelve la información detallada de la noticia pasada URL https://apirest.proyecto.danlucian.no-ip.info/v1/noticias/$noticiaRef Método GET Nombre de método para el parámetro signature noticiainfo 9.8.5.1 Parámetros de entrada No necesita de ningún parámetro de entrada extra; una simple llamada a dicha URL devolverá la información de la noticia. 9.8.5.2 Parámetros de salida Se entiende que estos son los parámetros del campo data. - noticiaRef: identificador de la noticia. - categoriaRef: identificador de la categoría de la noticia. - título: descripción de la noticia. Pequeño resumen de la noticia que aparece en el frontend de la aplicación también. Trabajo Fin de Grado Página 32 - usuario: nombre del usuario que creo el artículo. - tema: tema de la noticia. - valoración: valoración de la noticia. - extraCategories: las categorías adicionales a las que pertenece la noticia. - detalle: el texto completo de la noticia. 9.8.6 Alta de las listas de suscripción (alertas) Método que sirve para dar de alta al usuario en la lista de suscripción pasada. URL https://apirest.proyecto.danlucian.no-ip.info/v1/alertas/$alertaRef Método POST Nombre de método para el parámetro signature newuseralert 9.8.6.1 Parámetros de entrada - clientRef: identificador único de usuario. 9.8.6.2 Parámetros de salida No se devolverá nada en la posición data. Con el resto de campos comunes de respuesta (status, code y description) se comprobará si la operación se ha realizado con éxito o ha habido algún error. 9.8.7 Baja de las listas de suscripción (alertas) Método que sirve para dar de baja al usuario de la lista de suscripción pasada. URL https://apimobiledev.servidoresdns.net/rest/v1/alertas Método DELETE Nombre de método para el parámetro signature deluseralert 9.8.7.1 Parámetros de entrada - clientRef: identificador único de usuario. 9.8.7.2 Parámetros de salida No se devolverá nada en la posición data. Con el resto de campos comunes de respuesta (status, code y description) se comprobará si la operación se ha realizado con éxito o ha habido algún error. 9.9 Aspectos de seguridad Apartado que añadirán aspectos de seguridad del API complementarios a la documentación anterior. Trabajo Fin de Grado Página 33 9.9.1 Validaciones/Seguridad del API En este apartado se detallarán todos aquellos controles de seguridad que aplicarán a todos los métodos de la API. Adicionalmente, cada método tendrá una serie de validaciones adicionales que se detallarán de manera individual. Cada error tendrá su código de error y será devuelto a la aplicación (ver Anexo). 1) Número de peticiones por unidad de tiempo El objetivo de esta validación consiste en no permitir que desde una IP se superen más de X peticiones por unidad de tiempo. Para ello, los pasos a seguir son los siguientes: Definir constantes para limitar el número de peticiones. If(!defined(‘LIMITACION_LLAMADAS_MINUTO’)) define(‘LIMITACION_LLAMADAS_MINUTO’,100); Con estos valores se indica que no se pueden superar las 100 peticiones por minuto y podrán ser modificados después. Crear el método Authentication_API_Method en el fichero \api\modules\authentication\authentication.inc.php, él se encargara de hacer las validaciones necesarias. Crear el método Interface_Execute_Method. 2) Validación de token, timestamp y firma Hay 3 métodos que tendrán esta validación: - Listado de alertas - Baja/alta del usuario a listas de suscripción. Estos métodos recibirán los 3 parámetros que se han comentado en puntos anteriores: - accessKeyId: se validará que exista el token (clientRef) en nuestra base de datos, en la tabla un_users. - timestamp: se validará que la hora que nos llega como parámetro y la que tiene el servidor no supere los 15 minutos. Si supera este tiempo, se rechaza la petición y se devuelve el error correspondiente. - signature: se validará que la firma que se pasa como parámetro y la que se conforma en el servidor coincidan. Si no coinciden, se rechaza la petición y se devuelve el error correspondiente. Estas validaciones se harán en el método Authentication_API_Method del fichero \api\modules\authentication\authentication.inc. Trabajo Fin de Grado Página 34 3) Validación de que la operación solicitada corresponde al cliente que ha realizado la llamada. Esta validación no aplica a todos los métodos sino a aquellos métodos que permitan realizar una operación sobre un “elemento” que pueda no pertenecer al cliente. En nuestro caso no será necesario ya que en los métodos que necesitan dicho funcionamiento con validar que existe el usuario y se encuentra en un estado valido será suficiente. Esta validación seria valida en operaciones que se podrían dar en versiones futuras como la baja de artículos o la modificación de éstos. Ejemplo: método para modificar una noticia Este método recibe, entre otros parámetros, el ID de la noticia a modificar. El objetivo de esta validación consiste en que un cliente no pueda modificar los datos de una noticia que pertenece a otros usuarios si no tiene permisos para ello. Esta validación debería meterse en el metodo Authentication_API_Method el cual, después de las validaciones comentadas quedará de la siguiente forma: Authentication_API_Method ($remoteIP,$accessKeyId=null,$timestamp=null,$signature=null,$function4Signature=null), donde - $remoteIP IP del dispositivo móvil desde el que se realiza la petición. - $accesKeyId token ya comentado. Admite valor null por defecto, porque solo hay 3 métodos que dispondrán de este dato. - $timestamp fecha ya comentada. Admite valor null por defecto, porque solo hay 3 métodos que dispondrán de este dato - $signature firma ya comentada. Admite valor null por defecto, porque solo hay 3 métodos que dispondrán de este dato - $function4Signature nombre “interno” que damos al método para poder validar la firma Admite valor null por defecto, porque solo hay 3 métodos que dispondrán de este dato Con estos valores, lo que debe realizar el método Authentication_API_Method es lo detallado anteriormente 4) Identificadores de BBDD Existe un requisito de seguridad que consiste en que en los parámetros de entrada y salida de los métodos del API no vayan los identificadores de las bases de datos internas (ID de noticia, ID de categoría, ID de alerta, etcétera). Trabajo Fin de Grado Página 35 Para ello, como norma general, utilizaremos los métodos de encriptado y desencriptado que existen en el fichero \api\lib\encriptacion_lib.php En este caso utilizaremos una clave de encriptado que definiremos como constante en nuestro API: define('CLAVE', ‘proyecto.danlucian’); 9.10 Modulado funciones Para las funciones necesarias para el API se crearan módulos. Para la creación de un nuevo módulo como norma general se decidirán en función del objeto que tiene que tratar. De esta forma se crearan módulos que se llamaran api_$elemento donde elemento es el objeto a tratar en las funciones. Conforme a lo explicado se crearan 3 módulos llamados: api_noticias: contendrá funciones que tratan las noticias de la aplicación. Listado, detalle, filtrado de noticias. api_categorias: contendrá funciones que tratan las categorías de la aplicación. Listado de categorías. api_alertas: contendrá funciones que tratan las alertas de la aplicación. Listado de alertas, baja de la alerta del usuario, alta de la aleras del usuario. El hecho de crear un nuevo módulo es para que no se tenga que compilarse tanto código PHP en el servidor. Así que este módulo debe incluir el menor número posible de requires. De esta forma también hacemos más fácil detectar errores y tener el código más estructurado. Nota: Hay que validar todos los parámetros que lleguen a los métodos procesador. 9.10.1 Módulo api_noticias 9.10.1.1 Función listarNoticias Método que obtiene el listado de noticias publicadas en la aplicación. listarNoticias($top = null, $min =null) Se conectara a la BD de la aplicación y ejecutara la consulta de debajo sobre las tablas que utiliza Joomla para las noticias, categorías y usuarios y devolverá el resultado: SELECT i.id,i.title,c.NAME,u.userName FROM un_k2_items AS i JOIN un_k2_categories AS c ON i.catid = c.id JOIN un_k2_users AS u ON i.created_by = u.userID WHERE i.published = 1 9.10.1.2 Función filtrarNoticias Método que obtiene el listado de noticias publicadas en la aplicación aplicando el filtro de los parámetros pasados. Trabajo Fin de Grado Página 36 filtrarNoticias ($user = null, $categoria = null, $titulo = null, $top = null, $min = null) Se conectara a la BD de la aplicación y ejecutara la consulta de debajo sobre las tablas que utiliza Joomla para las noticias, categorías y usuarios y devolverá el resultado: SELECT i.id,i.title,c.NAME,u.userName FROM un_k2_items AS i JOIN un_k2_categories AS c ON i.catid = c.id JOIN un_k2_users AS u ON i.created_by = u.userID WHERE i.published = 1 and ( (u.name =? or u.username = ? ) or (c.name = ?) or (i.title = ?) ) 9.10.1.3 Función detalleNoticia Método que obtiene el detalle de la noticia pasada. detalleNoticia($idnoticia) Se conectara a la BD de la aplicación y ejecutara la consulta de debajo: SELECT i.id AS noticiaRef,i.title AS titulo,c.id AS categoriaRef,u.userName AS usuario, i.extra_fields AS camposExtra,i.FULLTEXT AS detalle, ac.catid AS extraCategories FROM un_k2_items AS i JOIN un_k2_categories AS c ON i.catid = c.id JOIN un_k2_users AS u ON i.created_by = u.userID LEFT JOIN un_k2_additional_categories AS ac ON i.id = ac.itemID WHERE i.published = 1 AND i.id=? 9.10.2 Módulo api_categorías 9.10.2.1 Función listarCategorias Método que obtiene el listado de categorías publicadas en la aplicación. listarCategorias () Se conectara a la BD de la aplicación y ejecutara la consulta de debajo sobre las tablas que utiliza Joomla para las categorías y devolverá el resultado: SELECT c.id,c.NAME FROM un_k2_categories WHERE c.published = 1 Trabajo Fin de Grado Página 37 9.10.3 Módulo api_alertas 9.10.3.1 Función listarAlertas Método que obtiene el listado de alertas publicadas en la aplicación. listarAlertas () Se conectara a la BD de la aplicación y ejecutara la consulta de debajo sobre la tabla que utiliza Joomla para las alertar y devolverá el resultado: SELECT ID, TITLE, DESCRIPTION FROM un_jma_alerts WHERE state = 1 9.10.3.2 Función altaAlerta Método que asocia el usuario a la alerta seleccionada. altaAlerta ($user,$alerta) Comprueba que se trata de un $user valido y activo. Comprueba que la $alerta existe Si el usuario tiene otras alertas esas se desasocian haciendo un DELETE en la tabla un_jma_subscribers. Para dar de alta al usuario en la alerta de hace un INSERT en la tabla un_jma_subscribers. Se devuelve error si ha fallado alguno de los pasos anteriores o true si no. 9.10.3.3 Función bajaAlerta Método que desasocia el usuario de toda alerta a la que está asociado. bajaAlerta($user) Ejecuta un DELETE de la tabla un_jma_subscribers para el usuario $user. 9.11 Vista de Datos 9.11.1 Modelo de base datos Debido a que este proyecto se basa en el CMS Joomla no hay que diseñar ninguna BD ya que viene instalada con la aplicación y todos los demás plugins utilizados crean sus propias tablas. Aparte de eso sí que hay ciertas funcionalidades de la aplicación que necesitan de unas tablas maestras para guardar datos y para ello se ha decidido crear unas tablas que darán soporte a dichas funcionalidades. Las operaciones que guardaran datos en BD serán: Cada llamada al API es necesario guardarla para poder hacer un recuento de cuantas llamadas se han hecho en un intervalo de tiempo indicado por la limitación de Trabajo Fin de Grado Página 38 seguridad mencionada antes. Para ello se crea la tabla API_REQUESTS, esta tabla se creara en la misma BD que se utilizó para la instalación de Joomla. Mensaje de los códigos de error de la aplicación. Para no tener códigos de error definidos por todos los módulos de la aplicación se creara una tabla que guardara la información correspondiente a cada id de error que devolverá el API. Para ello se creara la tabla API_ERRORS_MESSAGE y siempre que se devuelve un error se consultara dicha tabla para devolver la descripción adecuada en cada caso. Para ver un listado de los posibles errores ver anexo. Tablas API_REQUESTS Esta tabla maestra contiene todas las peticiones hechas a la aplicación mediante los métodos del API. APIR_ID (int, NOT NULL): Identificados de la fila a insertar. PK de la tabla. APIR_IP (varchar(50), NOT NULL): IP del cliente que realizo la petición. APIR_FECHA (datetime, NOT NULL): fecha de la petición. APIR_FUNCTION (varchar(255), NOT NULL): función de la petición. Para uso interno para ver si hay algún ataque, muchas llamadas en poco tiempo a la misma función. API_ERRORS_MESSAGE Esta tabla maestra contiene todos los tipos posibles de mensajes que puedan ser devueltos por los métodos del webservice que utiliza la aplicación. APIM_CODIGO (int, NOT NULL): código del mensaje a mostrar. PK de la tabla. APIM_VISIBLE_MESSAGE (varchar(1000), NOT NULL): texto con el mensaje a mostrar. Es el texto que se pasara al cliente que realizo la llamada. APIM_DESCRIPCION (varchar(1000), NULL): descripción del error para uso interno. Este mensaje será más descriptivo. Ejemplo: o o o APIM_CODIGO: 1 APIM_VISIBLE_MESSAGE: Error listando las noticias. APIM_DESCRIPCION: Error al ejecutar la consulta del listado de noticias. 10. Implementación Iteración 4 Este apartado detallara los pasos hechos para realizar la implementación y el encaminado de una petición REST. Antes de empezar tengo que explicar que el desarrollo de esta API se ha realizado teniendo en cuenta que en un futuro podría ser implementada una API SOAP sobre lo mismo así que lo que Trabajo Fin de Grado Página 39 se ha hecho ha sido desarrollar la API REST como una interfaz sobre unas clases que identifican los métodos y que se podrán instanciar desde una API SOAP si se decide implementar también en un futuro. La única diferencia de un API REST normal es que en lugar de ejecutar las acciones en cada uno de los objetos estos se ejecutan llamando a unas clases que se identifican por el nombre del método. 10.1 Pasos 10.1.1 Centralizar peticiones El primer paso ha sido el de crear un fichero “.htacces” que redirija toda petición a un fichero index.php que se encargara de ejecutar la petición. Para ello se ha creado la carpeta [ruta_base]\api\www\rest que contiene un fichero “index.php” que se encargara de las peticiones. Dentro de la carpeta REST tenemos los ficheros de debajo: El fichero “.htaccess” se encargara de redirigir cualquier petición a la carpeta REST, o cualquier otra que tenga como base a la carpeta REST, al fichero index.php 10.1.2 Procesar petición El fichero index.php instancia la clase “Request” que se encarga de sacar la información referente a la versión, objeto a instanciar, método utilizado, parámetros de la petición que nos han llegado. Una vez sacados todos los datos necesarios se realiza la llamada pedida a la clase del objeto. 10.1.3 Versionado Para mantener un control de versiones se ha implementado un versionado en la propia URL. De esta forma cada petición tendrá el formato: [RUTA BASE][Versión formato V [0-9]][Identificación de objeto] Ejemplo: https://apirest.proyecto.danlucian.no-ip.info/v1/noticias Trabajo Fin de Grado Página 40 La instancia del “Request” hecha en el index.php se encargara de romper la url y encaminar cada una de las peticiones además la clase contiene variables para detectar si se está haciendo una llamada a una versión en desuso, actual o que no esté implementada. 10.1.4 Recursos, objetos, clases Cada una de las URL se encuentra mapeada a un objeto que tendrá 4 funciones creadas por cada método por el cual se puede pedir una URL POST/PUT/GET/DELETE. En algunos casos las clases no tienen todos los métodos definidos ya que no es posible hacer peticiones con ese método al objeto. De lo explicado si se puede llamar a un objeto con todos los métodos, dicho objeto tiene que tener las funciones postAction, putAction, getAction, deleteAction implementadas. 10.2 Componentes 10.2.1 Carpetas base [ruta_base]\api\www\rest 10.2.1.1 Ficheros Index.php .htaccess 10.2.2 Carpeta Objetos [ruta_base]\api\modules\objetos 10.2.2.1 Ficheros Request.php V1 Carpeta que contiene los controladores de objetos. Clases que identifican cada una de las acciones. index.inc.php se encarga de instanciar las clases de las acciones. Para ver en más detalle una petición REST ver anexo. Trabajo Fin de Grado Página 41 11. ANEXOS 11.1 Códigos de Error API A continuación se listan los diferentes códigos de error y descripciones que puede devolver el API. Nota: el listado de códigos de error puede ir creciendo conforme se controlen más excepciones y aumenten los métodos del Web Service. La nomenclatura será la siguiente: - 1XXX: errores en la autenticación. - 2XXX: error en el formato de los parámetros de las peticiones. - 3XXX: error en la operación. - 5XXX: errores relativos al servidor. Código Descripción 1001 No existe el usuario. 1002 Máximo número de peticiones alcanzadas 1003 Acceso denegado 1004 Las credenciales de autenticación no son válidas. 1005 AccessKeyId no válida 1006 Formato de Timestamp no válido 1007 La firma indicada no coincide con la esperada 1008 La petición ha expirado. Este error se produce cuando la marca de tiempo (timestamp) difiere en más de 15 minutos con la fecha y hora del servidor. 1009 La versión utilizada es demasiado antigua 2001 La función especificada no existe 2002 Falta alguno de los parámetros obligatorios en la llamada a la función. 2003 Alguno de los argumentos indicados en la función no es válido. 3001 No se puede obtener información del usuario 3002 No se ha podido cambiar la alerta del usuario. 3003 No se ha podido obtener el listado de categorías. 3004 No se ha podido obtener el listado de noticias. 3005 No se ha podido obtener el listado de alertas. Trabajo Fin de Grado Página 42 3006 Error de conectividad de BBDD 3007 Información no valida al ejecutar la consulta en BBDD 3008 Se ha llegado al límite de recursos. 5001 Servicio no disponible. 5002 Error en la operación. 11.2 REST - REpresentational State Transfer La idea principal de REST es la de tener un sistema de redirecciones que mapea URL con recursos (objetos) sobre los que se podrán hacer peticiones en función de los métodos que se implementan. Aunque la idea de REST no se encuentra ligada a ningún protocolo en concreto la mayoría de nosotros cuando hablamos de REST nos referimos a REST sobre http y por lo tanto los métodos a utilizar en este caso son GET/POST/PUT/DELETE, etc. La gran diferencia entre REST y otras formas de implementar una API es que REST intenta utilizar la potencia del protocolo http al máximo aprovechándose de casi todo lo que esta provee. De esta forma nos encontramos los principios básicos de REST: - - - - - Cada uno de los recursos (objetos) de tu web tienen un id que será representado por la URI. Ejemplos: www.prueba.com/noticias, www.prueba.com/alertas, www.prueba.com/noticia/1234 etc. Esto ayuda en la depuración de errores y a la hora de entender mejor la aplicación. Utilizar los métodos que ofrece el servicio sobre el que implementas REST, como en este caso es http se utilizaran solamente los métodos que este posee, POST,PUT,GET,DELETE, etc. Aunque es bastante limitado es suficiente para realizar las operaciones necesarias sobre los objetos identificados anteriormente. Posibilidad de implementar la entrada como la salida con diferentes formatos, ej : json, xml, texto plano, o cualquier otro formato personalizado que lo pueda entender la aplicación que hace las peticiones. Con esto se consigue una aplicación muy escalable y que es capaz de dar soporte a varios sistemas a la vez teniendo así solamente una interfaz para varios clientes diferentes en lugar de tener una por cada tipo de cliente que se puede tener. La ventaja de utilizar el protocolo http es que permite una gran interoperabilidad con cualquier sistema desarrollado mediante algún lenguaje que tenga librerías para el http que hoy en día son la mayoría. Además la facilidad de elegir la representación de los datos a nivel de http es muy fácil simplemente estableciendo las cabeceras adecuadas tanto para identificar que formato de datos se manda como los que se aceptan(cabeceras content-type y accepted). Otra característica de REST es que es una forma de interactuar con el servidor sin utilizar estados ya que cada operación se realiza sobre cada recurso que el servidor gestiona y este ofrece solamente el estado en el que dicho recurso se encuentra. Si Trabajo Fin de Grado Página 43 es necesario la utilización de sesiones estas tendrían que hacerse desde la perspectiva del cliente que será el que se encarga de gestionarlas. 11.2.1 Ejemplo CRUD En el caso de una aplicación web se intentan mapear recursos con URL utilizando el protocolo http y sus métodos en principio PUT/POST/GET/DELETE. El API REST no es más que una librería que se encarga de procesar las peticiones http/s recibidas con sus parámetros y redirigir la petición hacia un recurso que se establece mediante un mapeo de la URL. Para identificar lo que se tiene que hacer el servidor con el recurso que se pide antes de devolver la respuesta se utilizan los métodos que el protocolo ofrece ej: Recurso: www.prueba.com/api/v1/noticias Sobre el recurso de arriba se pueden hacer varias peticiones que identifican la acción a realizar sobre el recurso. -Si se hace una petición GET se devuelve la lista de noticias. -Si se hace una petición POST, se interpreta que se desea crear una noticia. Tanto en el caso de PUT como el de DELETE a la URL de arriba se le añade un id de la forma de debajo para tener identificada la noticia sobre la que se desean hacer las operaciones sin necesidad de pasar parámetros extra para identificarlo y por tanto romper la idea de que mediante la URL y la petición se identifique la acción y el elemento sobre el que se desea realizar la acción: Recurso: www.prueba.com/api/v1/noticias/idnoticia -Si se hace una petición PUT, se interpreta que se desea modificar los datos de la noticia. -Si se hace una petición DELETE, se interpreta que se desea eliminar la noticia. De esta forma mediante la URL y el método se identifica perfectamente la acción que se desea realizar y como datos se mandan los parámetros necesarios para efectuar cada una de las acciones arriba mencionadas. Una petición REST en este caso tiene tres componentes: 1. URI identifica el objeto sobre el que se realizara la acción. 2. Metodo http utilizado (POST/GET/PUT/DELETE) identifica la acción a llevar a cabo. 3. Datos pasado son los datos necesarios para llevar a cabo la operación. Trabajo Fin de Grado Página 44 Este mismo funcionamiento se puede dar mediante la utilización de diferentes formas de crear la URL pero se ha elegido esta en el desarrollo de nuestro API para tener bien definidos los conceptos básicos de REST. 11.2.2 Ejemplo POST Como ejemplo se puede implementar el mismo funcionamiento utilizando solamente llamadas POST pero de esta forma se tendría que meter en la URL un verbo para identificar la acción ya que no será posible hacerlo simplemente con el método utilizado. Ejemplo: Recurso: www.prueba.com/api/v1/noticias/idnotiaia/info mediante POST la información de la noticia. Recurso: www.prueba.com/api/v1/noticias/ mediante POST crea una noticia. Recurso: www.prueba.com/api/v1/noticias/idnoticia/modify mediante POST modifica una noticia. Recurso: www.prueba.com/api/v1/noticias/idnoticia/delete noticia. mediante post elimina una Como se puede ver se mantiene la idea pero no la forma ya que se pierde la utilización del protocolo http mediante sus métodos. 11.3 Ejemplo petición post api REST 11.3.1 Petición https://apirest.proyecto.danlucian.no-ip.info/v1/alertas/$alertRef POST + Parámetros 1. El fichero index.php instancia la clase Request.php 2. La clase Request.php obtiene la información de la petición. Obtiene la versión, la clase el método que se utiliza y los parámetros(también los decodifica pero eso no nos interesa para explicar el funcionamiento) 3. La clase Request utilizando el nombre del objeto sacado “alertas” y la versión”v1” instancia la clase controlador AlertasController de la carpeta v1 y llama a la función postAction de esta. Trabajo Fin de Grado Página 45 4. Esta función se encargara de llamar a la función altaUserAlertasAction que se encuentran definidas en el fichero index.inc.php. este fichero tiene definidas todas las funciones a las que se llamaran desde los controladores. La función postAction de arriba tiene contenidas dos posibles llamadas mediante POST aunque una está comentada esta puesta para mostrar el posible funcionamiento: https://apirest.proyecto.danlucian.no-ip.info/v1/alertas nuevaAlertaAction. https://apirest.proyecto.danlucian.no-ip.info/v1/alertas/idalerta altaUserAlertasAction. 5. A partir de este paso se instancia la clase correspondiente y se ejecuta el método doAction de dicha clase. Este se encargara de hacer hacer las llamadas que compruebas las validaciones de seguridad y de llamar al método correspondiente una vez pasadas todas las validaciones. 6. Hay que tener en cuenta antes de devolver el resultado de establecer la cabecera para identificar el formato de datos de vas a devolver. header('Content-Type: application/json; charset=utf-8'); 11.3.2 Notas Este API se ha desarrollado teniendo en cuenta que solamente se recibirán datos en formado json con sus respectivas codificaciones necesarias y que solamente se envían datos en formato json. Esto se ha decidido así por las características del proyecto y por los tiempos a dedicar. No se ha hecho uso de ningún framework que nos facilite dicho funcionamiento ya que en un inicio se ha probado con una versión de php4 y para ello no existe ningún framework de en REST para creación de APIs, así que se ha hecho un trabajo de investigación y se ha desarrollado uno desde cero. Si en un futuro se desea implementar en otros tipos de formatos de salida antes de hacerlo mirar la versión de php ya que si es la 5 hay muchos frameworks que te ofrecen fácil solución a la hora de crear APIs REST y que te devuelvan los datos en muchísimos formatos ya conocidos o personales. Trabajo Fin de Grado Página 46
