Skip to content

Laboratoria/DEV015-fleet-management-api

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
docs
docs
 
 
postman
postman
 
 
README.md
README.md
 
 
explaindev.json
explaindev.json
 
 
thumb.png
thumb.png
 
 

Repository files navigation

Fleet Management Software API

Índice

1. Preámbulo

De acuerdo con Wikipedia, la internet de las cosas (IoT, por sus siglas en inglés)​ es un concepto que se refiere a una interconexión digital de objetos cotidianos con internet. Constituye un cambio radical en la calidad de vida de las personas en la sociedad, ofreciendo nuevas oportunidades en el acceso a datos, educación, seguridad, asistencia sanitaria y en el transporte, entre otros campos. Por ejemplo, en logística y manejo de flotas, se puede hacer seguimiento en todo momento de la ubicación y las condiciones de vehículos mediante sensores inalámbricos conectados a internet que envían alertas en caso de eventualidades (demoras, daños, robos, etc.).

zach-vessels-utMdPdGDc8M-unsplash

La IoT también plantea retos como el almacenamiento, análisis y visualización de la gran cantidad de información que genera. Se calcula que para el 2025 los dispositivos IoT generen 79.4 zettabytes (1 zettabyte equivale a 1 trillón de gigabytes). Como desarrolladoras debemos estar al tanto de estos retos y contribuir para su solución desde nuestra experiencia, conocimiento y ganas de aprender.

2. Resumen del proyecto

En este proyecto construirás la API REST de un Fleet Management Software para consultar las ubicaciones de los vehículos de una empresa de taxis en Beijing, China.

Te entregaremos las ubicaciones de casi 10 mil taxis. Esperamos que como desarrolladora explores nuevas alternativas y técnicas para almacenar y consultar esta información y puedas garantizar la mejor experiencia de usuaria en tu API REST.

3. Objetivos de aprendizaje

Reflexiona y luego marca los objetivos que has llegado a entender y aplicar en tu proyecto. Piensa en eso al decidir tu estrategia de trabajo.

Python

Tipos de datos

Funciones

Iteración

Testing en Python

Modularización

Manejo de dependencias

Flask

Rutas (Flask)

Request Object (Flask)

Response Object (Flask)

Testing en Flask (Flask)

Java

  • Modificadores de acesso (public, private, protected)

  • Variables

  • Uso de condicionales

  • Uso de bucles (Loops)

Tipos de data

  • Primitivos

  • Datos primitivos vs no primitivos

  • Cadenas

  • Arreglos

Colecciones

  • ArrayList

  • HashMap

  • HashSet

Testing

  • JUnit

  • Mockito

Spring Framework

  • Entidad

  • Repositorio

Conceptos Core (Spring Framework)

  • Beans

  • Inversión de Control

  • Anotaciones

Spring Web (Spring Framework)

  • RestController

  • RequestMapping

  • RequestParam

Testing (Spring Framework)

  • Spring Test

  • Hamcrest

Hibernate ORM

  • Configuración

  • Esquema

  • Entidad

  • Tabla

  • Columna

  • Identificadores

  • Asociaciones

  • Colecciones

  • Persistencia

  • Consultas

Programación Orientada a Objetos (OOP)

  • Clases

  • Objetos

  • Métodos

  • Atributos

  • Constructores

  • Encapsulamiento

  • Abstracción

  • Composición

  • Interfaces

  • Herencia (super, extends, override)

  • Lenguaje de Modelado Unificado (UML, class diagrams)

HTTP

Autenticación

  • JWT (JSON Web Token)

  • Almacenamiento y acceso de contraseñas

SQL

Bases de datos

  • Modelado de datos

  • Conexión

PostgreSQL

Control de Versiones (Git y GitHub)

Git

  • Git: Instalación y configuración

  • Git: Control de versiones con git (init, clone, add, commit, status, push, pull, remote)

  • Git: Integración de cambios entre ramas (branch, checkout, fetch, merge, reset, rebase, tag)

GitHub

  • GitHub: Creación de cuenta y repos, configuración de llaves SSH

  • GitHub: Colaboración en Github (branches | forks | pull requests | code review | tags)

  • GitHub: Organización en Github (projects | issues | labels | milestones | releases)

4. Consideraciones generales

  • Este proyecto se debe "resolver" en duplas.
  • El rango de tiempo estimado para completar el proyecto es de 4 a 6 Sprints.

5. Criterios de aceptación del proyecto

Nuestra cliente ha instalado dispositivos GPS en sus taxis. Estos dispositivos utilizan señales satelitales para determinar con precisión las coordenadas geográficas del taxi.

Nuestra clienta requiere:

  1. Cargar la información de archivos SQL a una base de datos PostgreSQL.
  2. Desarrollar una API REST que permita consultar, mediante peticiones HTTP, la información almacenada en la base de datos.

Definición del producto

El Product Owner nos presenta este backlog que es el resultado de su trabajo con la clienta hasta hoy y la documentación de la API REST a desarrollar.

[Historia de usuario 1] Cargar información a base de datos

Yo, como desarrolladora, quiero cargar la información almacenada hasta ahora en archivos sql en una base de datos PostgreSQL, para facilitar su consulta y análisis.

Criterios de aceptación
  • Se debe tener en cuenta el siguiente diagrama para la implementación de las relaciones entre las tablas

mer

  • La tabla de trajectories se debe crear con el "id" que se incremente automáticamente (SERIAL) para poder insertar los valores sin necesidad de especificar un identificador
Definición de terminado
  • La base de datos tiene creada la tabla de taxis
  • La tabla de taxis tiene cargada la data de taxis
  • La base de datos tiene creada la tabla de trayectorias
  • La tabla de taxis tiene cargada la data de trayectorias

[Historia de usuario 2] Endpoint listado de taxis

Yo como clienta de la API REST requiero un endpoint para listar todos los taxis.

Por ejemplo, este endpoint podria ser usado por una aplicación web para filtrar un listado de taxis.

Posible uso del endpoint GET /taxis

Animación que muestra un menú desplegable para elegir un taxi. Las opciones se filtran según el text que se escriba en la lista.

Criterios de aceptación
  • El endpoint es implementado de acuerdo a la documentación swagger. a excepción de la respuesta 401 que sera implementada hasta la Historia de Usuaria 7.
  • El endpoint responde para cada taxi: id y placa.
  • El endpoint paginamos los resultados para asegurar que las respuestas sean más fáciles de manejar.
  • El endpoint soporta un parametro plate para retornar unicamente los taxis cuya placa contenga el texto especificado
  • El endpoint paginamos los resultados para asegurar que las respuestas sean más fáciles de manejar.
Definición de terminado
  • El código del endpoint debe recibir code review de al menos una compañera.
  • El código del endpoint debe estar cargado en un repositorio de Github.
  • El código del endpoint debe contar con test unitarios.
  • Pasa los tests de endpoint /taxis en la colección postman.

[Historia de usuario 3] Endpoint historial de ubicaciones

Yo como clienta de la API REST requiero un endpoint para consultar todas las ubicaciones de un taxi dado el id y una fecha.

Por ejemplo, este endpoint podría ser usado por una aplicación web para mostrar en un mapa la trayectoria de un taxi.

Posible uso del endpoint GET /trajectories/{taxiId}

Animación que muestra en un mapa la trayectoria de un taxi.

Criterios de aceptación
  • El endpoint es implementado de acuerdo a la documentación swagger a excepción de la respuesta 401 que sera implementada hasta la Historia de Usuaria 7.
  • El endpoint responde para un id de taxi y una fecha mostrando la siguiente información: latitud, longitud y timestamp (fecha y hora).
Definición de terminado
  • El código del endpoint debe recibir code review de al menos una compañera.
  • El código del endpoint debe estar cargado en un repositorio de Github.
  • El código del endpoint debe contar con test unitarios.
  • Pasa los tests de endpoint /trajectories en la colección postman.

[Historia de usuario 4] Endpoint última ubicación

Yo como clienta de la API REST requiero un endpoint para consultar la última ubicación reportada por cada taxi.

Por ejemplo, este endpoint podria ser usado por una aplicación web para mostrar en una mapa la última posición de cada taxi.

Posible uso del endpoint GET /trajectories/latest

Animación que un listado de taxis y al hacer clic en cada uno muestra un mapa la última posición de un taxi.

Criterios de aceptación
  • El endpoint es implementado de acuerdo a la documentación swagger a excepción de la respuesta 401 que sera implementada hasta la Historia de Usuaria 7.
  • El endpoint responde para cada taxi la siguiente información: id, placa, latitud, longitud y timestamp (fecha y hora).
  • Pasa los tests de endpoint /trajectories/latest en la colección postman.
Definición de terminado
  • El código del endpoint debe recibir code review de al menos una compañera.
  • El código del endpoint debe estar cargado en un repositorio de Github.
  • El código del endpoint debe contar con test unitarios.

[Historia de usuario 5] Gestión de usuarios

Yo, como clienta de la API REST, requiero un conjunto de endpoints para poder realizar operaciones CRUD (Crear, Leer, Actualizar, Eliminar) sobre los usuarios de la plataforma.

Criterios de aceptación
  • Crear un endpoint para la creación de usuarios de acuerdo a la documentación Swagger proporcionada.
  • Desarollar un endpoint para la obtención de usuarios de acuerdo a la documentación Swagger proporcionada.
  • Implementar un endpoint para actualizar la información de un usuario existente de acuerdo a la documentación Swagger proporcionada.
  • Crear un endpoint para eliminar un usuario de acuerdo a la documentación Swagger proporcionada.
  • No implementar la respuesta 401 pues sera implementada hasta la Historia de Usuaria 7.
Definición de terminado
  • El código de los endpoints debe pasar por una revisión de código realizada por al menos una compañera.
  • El código de los endpoints debe contar con test unitarios.
  • Pasa los tests de endpoints /users en la colección postman.

Por supuesto, aquí tienes la historia de usuario para un endpoint de login que devuelve un JWT (JSON Web Token) dado un correo electrónico y contraseña válidos:

[Historia de usuario 6] Autenticación de usuarios mediante JWT

Yo, como clienta de la API REST, necesito un endpoint para poder autenticarme en la plataforma utilizando mi correo electrónico y contraseña, y recibir un JWT válido que pueda ser utilizado para acceder a recursos protegidos.

Criterios de aceptación
  • Implementar el endpoint de autenticación de acuerdo a la documentación Swagger proporcionada.
  • El endpoint debe aceptar un correo electrónico y una contraseña válidos como parámetros de entrada.
  • Al autenticarse con éxito, el endpoint debe devolver un JWT que contenga la información de identificación del usuario.
  • El JWT generado debe tener un tiempo de expiración adecuado y debe ser válido para realizar peticiones a recursos protegidos durante ese tiempo.
  • El endpoint debe manejar adecuadamente los casos de error, devolviendo mensajes descriptivos en caso de credenciales inválidas o cualquier otro problema durante el proceso de autenticación.
Definición de terminado
  • El código del endpoint de login debe pasar por una revisión de código realizada por al menos una compañera.
  • El código del endpoint debe contar con test unitarios.
  • Pasa los tests de endpoint /login/auth en la colección postman.

[Historia de usuario 7] Protección de endpoints con JWT

Yo, como desarrolladora del sistema, necesito asegurarme de que todos los endpoints de la API estén protegidos utilizando un token JWT en el encabezado de autorización de cada petición, para garantizar la seguridad de los datos y recursos de la plataforma.

Criterios de aceptación
  • Configurar la API para que todos los endpoints requieran un token JWT válido en el encabezado de autorización de cada petición.
  • Implementar un middleware o interceptor en la capa de seguridad de la API para verificar la validez y autenticidad del token JWT en cada petición entrante.
  • En caso de recibir una petición sin un token JWT válido o sin token en el encabezado de autorización, la API debe devolver un código de estado HTTP 401 (Unauthorized) y un mensaje de error apropiado.
Definición de terminado
  • Todos los endpoints de la API deben estar protegidos con un token JWT en el encabezado de autorización.
  • El código del middleware o interceptor de seguridad debe pasar por una revisión de código realizada por al menos una compañera.
  • Se deben incluir test unitarios.
  • Pasa los tests de endpoints en la colección con auth en postman.

6. Stack de tecnologías

Puedes implementar este proyecto en JavaScript, Python o Java.

7. Testing

Incluido en el proyecto hay una suite de pruebas que se deben ejecutar para ver si tu API cumple con lo que espera la especificación. Debes ejecutar estas pruebas con cada historia de usuario para verificar que has completado la funcionalidad.

Las pruebas están incluidas en el directorio postman.

Para ejecutar las pruebas, puedes usar la extensión de Postman para Visual Studio Code, e importar el director postman. Pero para ejecutar toda la colección de pruebas simultáneamente (y de forma gratuita), necesitas instalar una herramienta de línea de comandos llamada newman.

Sigue las instrucciones para instalar newman globalmente. Luego puedes ejecutar la colección con el entorno incluido así:

newman run postman/collection.json -e postman/environment.json

postman/collection.json es una colección para los endpoints del API sin autenticación.

Si también completas las historias de usuario de autenticación del API, entonces ejecuta postman/collection-auth.json en su lugar.

Mostramos el proceso en este video de como correr pruebas de Postman.

Ambas colecciones se pueden ejecutar contra la base de datos de producción real, pero puedes considerar crear una base de datos de prueba ya que las pruebas para los endpoints de /user realizan operaciones CRUD y crean y eliminan un usuario cuyo correo es [email protected].

Para el login y los endpoints autenticados, tu base de datos necesita tener un usuario cuyas credenciales coincidan con las variables testUserEmail y testUserPassword de las pruebas del API que se encuentran en ./postman/environment.json, cuyos valores son [email protected] y test respectivamente. Recuerda que las contraseñas están encriptadas, por lo que tu usuario no tendrá test como una contraseña sin cifrar en tu base de datos.

Además de estas pruebas y cualquier prueba unitaria, puedes considerar escribir pruebas adicionales para probar los datos devueltos por tu API. Agregar una colección de pruebas adicional es una opción, o usar una biblioteca como supertest para Node u otra biblioteca con tu lenguaje de preferencia.

8. Pistas, tips y lecturas complementarias

Te proponemos los siguientes pasos para iniciar con el proyecto

Paso 1. Comprender que es una API REST

En primer lugar, asegúrate de comprender qué es una API REST. Para esto puedes consultar en internet o preguntarle a ChatGPT. Habla con una coach en tu proximo Office Hours para confirmar tus aprendizajes. En particular, te recomendamos ver leer este artículo.

Paso 2. Crear una instancia de PostgreSQL en Vercel

La base de datos recomendada para tu aplicación es PostgreSQL. Te recomendamos usar vercel PostgreSQL para que no tengas que instalar PostgreSQL en tu computadora.

Para crear una base de datos PostgreSQL en Vercel usa la documentación oficial. Identifica la siguiente información porque la necesitarás para conectarte a tu base de datos

  • POSTGRES_USER
  • POSTGRES_HOST
  • POSTGRES_PASSWORD
  • POSTGRES_DATABASE

Paso 3. Conectar la instancia de PostgresSQL usando pgAdmin

Una vez hayas creado una instancia de PostgreSQL en Vercel, deberás conectarte a ella. Te recomendamos que instales pgAdmin, un GUI (Graphical User Interface) para interactuar con la base de datos.

Con pgAdmin intenta conectarte a la base de datos usando la información suministrada por vercel.

Paso 4. Crear las tablas y cargar la información

En este punto, ya puedes trabajar en la Historia de Usuaria 1. Deberás crear las tablas en tu base de datos y cargar la información solicitada. Puedes crear una tabla usando la interfaz gráfica de pgAdmin o en usando SQL.

Paso 5. Crear tu primer endpoint

Ya es hora de escribir código. Tu primer objetivo es crear un proyecto que al ejecutarse cree un servidor HTTP que responda a la petición GET /taxis con un "hola mundo".

Te recomendamos usar Postman para confirmar que el endpoint que desarrolles responda segun lo solicitado.

El procedimiento recomendado dependerá del lenguaje de programación que hayas elegido:

Paso 6.Conectar la instancia de Postgresql desde código

Luego vas a necesitar elegir un módulo o librería para interactuar con nuestra base de datos desde el lenguaje de desarrollo elegido.

La librería recomendada dependerá del lenguaje de programación que hayas elegido:

  • Si estás usando NodeJS, puedes instalar y configurar Prisma
  • Si estás usando Java, puedes instalar y configurar Hibernate
  • Si estás usando Python, puedes instalar y configurar SqlAlchemy
  • Si estás usando C#, puedes instalar y configurar Npgsql

Paso 7. Modificar endpoint para consultar base de datos

Utiliza la librería elegida para consultar la base de datos y que tu API responda a la petición GET /taxis con el listado de taxis tal como se especifica en la documentación de API.

De nuevo, usa Postman para confirmar que el endpoint que desarrolles responda según lo solicitado.

Paso 8. Soportar parametros en el endpoint

De acuerdo a la documantación documantación el endpoint GET /taxis soporta 3 parametros: plate, page y limit.

Modifica tu código para soportar peticiones a tu endpoint con estos parámetros. Usa Postman para probar tu endpoint con diferentes valores de estos parámetros.

Paso 9. Escribir pruebas e2e para el endpoint

Elige un módulo o librería para escribir pruebas e2e de tu endpoint.

La librería recomendada dependerá del lenguaje de programación que hayas elegido:

  • Si estás usando NodeJS, puedes instalar y configurar Node-postgres o Prisma. Discute una coach cuales son las diferencias entre ambas librerías.
  • Si estás usando Java, puede instalar y configurar
  • Si estás usando Python, puedes instalar y configurar pytest
  • Si estás usando C#, puedes instalar y configurar

Paso 10. Implementar los demás endpoints

¡Felicitaciones! Hasta este punto ya has completado la Historia de Usuaria 2. Puedes continuar implementado las demás historias.

9. Funcionalidades opcionales

Si completaste todas las funcionalidades del proyecto te invitamos a trabajar en las funcionalides opcionales

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

4 watching

Forks

35 forks
Report repository

Releases

No releases published

Packages

No packages published