feat: Add first steps for starting with Fleet Management API (#1815)

* Add first steps for starting with project

* Hide django

* mdlint rules fixes

* Update projects/05-fleet-management-api/README.md

---------

Co-authored-by: Ivy Feraco <ivy@laboratoria.la>
Co-authored-by: Ivy Feraco <unjust@gmail.com>

projects/05-fleet-management-api/README.md

@@ -330,41 +330,140 @@ Puedes implementar este proyecto en JavaScript, Python o Java.
 
 ## 7. Pistas, tips y lecturas complementarias
 
-### Modelamiento de datos
+Te proponemos los siguientes pasos para iniciar con el proyecto
+
+### Paso 1. Comprender que es una API REST
+
+En primer lugar, asegurate 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]( https://dev.to/dennysjmarquez/todo-lo-que-necesitas-saber-sobre-api-rest-glosario-de-terminos-esenciales-y-mas-29pc).
+
+### 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](https://vercel.com/docs/storage/vercel-postgres)
 para que no tengas que instalar PostgreSQL en tu computadora.
 
-Una vez tengas acceso a una instancia de PostgreSQL, deberás crear tablas en
-tu base de datos para almacenar la información entregada. Te recomendamos
-entonces crear dos tablas, una para almacenar la información de taxis y otra
-para almacenar la información de ubicaciones. Deberás definir las columnas
-de cada tabla de acuerdo a la información entregada.
+Para crear una base de datos postgresql en Vercel usa la
+[documentación oficial](https://vercel.com/docs/storage/vercel-postgres/quickstart).
+Identifica la siguiente información porque la necesitarás para
+conectarte a tu base de datos
 
-Puedes crear una tabla en PostgreSQL usando
-[SQL](https://www.postgresqltutorial.com/postgresql-create-table/).
+* POSTGRES_USER
+* POSTGRES_HOST
+* POSTGRES_PASSWORD
+* POSTGRES_DATABASE
+
+### Paso 3. Conectar la instancia de PostgresSQL usando pgAdmin
 
-### Definir endpoints de API
+Una vez hayas creado una instancia de PostgreSQL en Vercel,
+deberás conectarte a ella. Te recomendamos que instales
+[pgAdmin](https://www.pgAdmin.org/download/),
+un GUI (Graphical User Interface) para interactuar con la base de datos.
 
-Deberás definir y documentar los endpoints de tu API.
-Debes usar [Swagger](https://swagger.io/) para esto.
+Con _pgAdmin_ intenta conectarte a la base de datos
+usando la información suministrada por vercel.
 
-Para una API REST debes definir para cada endpoint entre otras cosas el
-[método HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods),
-url, parámetros,
-[encabezados](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers),
-[códigos HTTP de respuesta](https://shorturl.at/bdegB)
-y
-[cuerpo](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages).
+### Paso 4. Crear las tablas y cargar la información
 
-Por ejemplo, en la siguiente figura se define un endpoint para consultar la
-información de los taxis en la aplicación. El método del endpoint es _GET_,
-la url es _/taxis_. Recibe un parámetro _query_, retorna la información con
-_código HTTP_ 200 en formato json gracias al _header_
-`Content-type` con valor `application/json`.
+En este punto, ya puedes trabajar en la
+[Historia de Usuaria 1](#historia-de-usuario-1-cargar-información-a-base-de-datos).
+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](https://www.postgresqltutorial.com/postgresql-create-table/).
 
-![Ejemplo Endpoint API Rest](https://firebasestorage.googleapis.com/v0/b/laboratoria-945ea.appspot.com/o/fleet-management-api-java%2Fexample-endpoint-api-rest.png?alt=media)
+### 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](https://learning.postman.com/docs/getting-started/first-steps/overview/)
+para confirmar
+que el endpoint que desarrolles responda segun
+lo solicitado.
+
+El procedimiento recomendado dependerá del lenguaje de programación
+que hayas elegido:
+
+* Si estás usando NodeJS, puedes seguir este
+[tutorial](https://hackernoon.com/how-to-setup-a-nodejs-app-with-express-and-typescript)
+para crear un servidor HTTP con express y TypeScript
+* Si estás usando Java, puedes seguir este
+[video de Primer Endpoint con Java](https://youtu.be/-FRu28PvH6Q)
+* Si estás usando Python, puedes seguir
+[el tutorial _Minimal Application_](https://flask.palletsprojects.com/en/3.0.x/quickstart/#a-minimal-application)
+de la documentación oficial de Flask
+* Si estás usando C#, puedes seguir
+[el tutorial de la  
+documantación oficial de C#](https://learn.microsoft.com/es-es/aspnet/core/tutorials/first-web-api?view=aspnetcore-8.0&tabs=visual-studio)
+
+### 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](https://www.prisma.io/docs/orm/overview/introduction/what-is-prisma)
+* Si estás usando Java, puedes instalar y configurar
+[Hibernate](https://docs.spring.io/spring-framework/reference/data-access/orm/hibernate.html)
+* Si estás usando Python, puedes instalar y configurar
+[SqlAlchemy](https://docs.sqlalchemy.org/en/latest/orm/quickstart.html)
+* Si estás usando C#, puedes instalar  y configurar
+[Npgsql](https://www.npgsql.org/doc/index.html)
+
+### 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](https://app.swaggerhub.com/apis-docs/ssinuco/FleetManagementAPI/1.0.0#/taxis/getTaxi).
+
+De nuevo, usa [Postman](https://learning.postman.com/docs/getting-started/first-steps/overview/)
+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](https://app.swaggerhub.com/apis-docs/ssinuco/FleetManagementAPI/1.0.0#/taxis/getTaxi)
+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](https://learning.postman.com/docs/getting-started/first-steps/overview/)
+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](https://node-postgres.com/)
+o
+[Prisma](https://www.prisma.io/docs/orm/overview/introduction/what-is-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](https://docs.pytest.org/en/8.1.x/)
+* 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.
 
 ## 8. Funcionalidades opcionales
 

projects/05-fleet-management-api/docs/stack-python-django.md

@@ -0,0 +1,77 @@
+# Fleet Management Software API en Python y Django
+
+Django es un framework web que fomenta el desarrollo rápido y limpio de
+aplicaciones web, el cual es pensado para fomentar la escalabilidad en
+el desarrollo.
+
+Entre las características más importantes es que Django trabaja con su propio
+[ORM (Object Relational Mapper)](https://es.wikipedia.org/wiki/Mapeo_relacional_de_objetos)
+para facilitar la interacción con la base de datos.
+
+Django es una excelente opción para desarrollar aplicaciones web complejas
+que requieren una amplia variedad de funcionalidades integradas,
+una arquitectura MVT (Model View Template) sólida y
+una gran comunidad de apoyo.
+
+* [Django](https://www.djangoproject.com):
+  como framework para implementar un servidor HTTP.
+* [Django REST Framework](https://www.django-rest-framework.org): como biblioteca
+complementaria para crear APIs web RESTful.
+* [Postgresql](https://www.postgresql.org/): como base de datos.
+
+## Pistas para trabajar con Django
+
+### Tus primeras instalaciones
+
+Para trabajar con Django puedes usar entornos virtuales
+en el siguiente [video](https://youtu.be/T2CZ7bltuMs) puedes guiarte para crear
+un entorno virtual, también hemos preparado un [video](https://youtu.be/YoKjtqxAXXw)
+que ejemplifica la forma en como inicializar un proyecto con Django.
+
+### Cargar la información a la base de datos
+
+Una vez tengas acceso a una instancia
+de PostgreSQL, la [historia de usuaria 1](../README.md#historia-de-usuario-1-cargar-información-a-base-de-datos)
+nos habla de crear las tablas para cargar la información.
+Uno de los caminos que te sugerimos es:
+
+1. Crear los modelos
+2. Después, generar las migraciones (usando el ORM de Django)
+3. Cargar la información a tu base de datos
+
+Para eso recomendamos primero tener una sola "app" para controlar todo lo
+relacionado a la administración de taxis y dentro de la app crear dos modelos,
+uno para almacenar la información de taxis (`taxis`) y otro para almacenar la
+información de ubicaciones (`trajectories`).
+
+Deberás definir los campos de cada modelo de acuerdo a la información entregada.
+Al momento de querer cargar la información es necesario que modifiques el script
+para especificar en que app trabajaran las 2 tablas hemos preparado el siguiente.
+
+Ejemplo de la modificación:
+
+```SQL
+-- Así se visualiza originalmente una linea en el script
+INSERT INTO trajectories (id, date, latitude, longitude ) VALUES ('10133','2008-02-02 13:47:59',116.37659,39.85567);
+```
+
+Agregando el nombre de la app (en este ejemplo nombramos el app `taxiapp`):
+
+```SQL
+-- Así se visualiza con el nombre de la tabla cambiado
+INSERT INTO taxiapp_trajectories (id, date, latitude, longitude ) VALUES ('10133','2008-02-02 13:47:59',116.37659,39.85567);
+```
+
+Puede realizar este cambio fácilmente con la función de buscar y reemplazar
+(find and replace), para todas las apariciones en scripts SQL.
+
+También, hay un [video para ejemplificar como agregar el app en el script](https://youtu.be/iwc9R7fF7P4).
+
+### Generando tus endpoints
+
+Con Django es posible integrar herramientas como
+Django rest framework para trabajar la creación de una API y su [documentación oficial](https://www.django-rest-framework.org)
+es clave para guiarte en la instalación y uso de la herramienta.
+
+Al momento en que empieces a documentar los endpoints
+de tu API. Debes usar [Swagger para rest framework](https://drf-yasg.readthedocs.io/en/stable/readme.html)

projects/05-fleet-management-api/docs/stack-python-django.pt.md

@@ -0,0 +1,80 @@
+# Fleet Management Software API en Python y Django
+
+Django é um framework web que incentiva o desenvolvimento rápido e limpo de
+aplicativos web, projetado para promover a escalabilidade no
+desenvolvimento.
+
+Entre as características mais importantes está o
+fato de que o Django trabalha com um
+[ORM (Mapeador Relacional de Objetos)](https://es.wikipedia.org/wiki/Mapeo_relacional_de_objetos)
+para facilitar a interação com o banco de dados.
+
+Django é uma excelente opção para desenvolver aplicativos web complexos
+que requerem uma ampla variedade de funcionalidades integradas,
+uma sólida arquitetura MVT (Model View Template) e
+uma grande comunidade de suporte.
+
+* [Django](https://www.djangoproject.com):
+  como framework para implementar um servidor HTTP.
+* [Django REST Framework](https://www.django-rest-framework.org): como biblioteca
+complementar para criar APIs web RESTful.
+* [Postgresql](https://www.postgresql.org/): como banco de dados.
+
+## Dicas para trabalhar com Django
+
+### Suas primeiras instalações
+
+Para trabalhar com Django, você pode usar ambientes virtuais.
+No seguinte [vídeo](https://youtu.be/T2CZ7bltuMs),
+você pode se orientar para criar
+um ambiente virtual, também preparamos um [vídeo](https://youtu.be/YoKjtqxAXXw)
+que exemplifica como inicializar um projeto com Django.
+
+### Carregando informações no banco de dados
+
+Depois de ter acesso a uma instância
+do PostgreSQL, a [história do usuário 1](../README.md#história-do-usuário-1-carregar-informações-no-banco-de-dados)
+fala sobre criar as tabelas para carregar as informações.
+Uma das abordagens que sugerimos é:
+
+1. Criar os modelos
+2. Em seguida, gerar as migrações (usando o ORM do Django)
+3. Carregar as informações no seu banco de dados
+
+Para isso, recomendamos primeiro ter um único "app" para controlar tudo
+relacionado à administração de táxis e dentro do app criar dois modelos,
+um para armazenar as informações dos táxis (`taxis`) e outro para armazenar as
+informações de trajetórias (`trajectories`).
+
+Você deve definir os campos de cada modelo de acordo com as informações fornecidas.
+Quando quiser carregar as informações, é necessário modificar o script
+para especificar em qual app as 2 tabelas trabalharão. Preparamos o seguinte.
+
+Exemplo de modificação:
+
+```SQL
+-- Assim é como uma linha é originalmente visualizada no script
+INSERT INTO trajectories (id, date, latitude, longitude ) VALUES ('10133','2008-02-02 13:47:59',116.37659,39.85567);
+```
+
+Ao usar o nome do app (neste exemplo, chamamos o app de `taxiapp`):
+
+```SQL
+-- Assim é como a linha é visualizada com o nome da tabela alterado
+INSERT INTO taxiapp_trajectories (id, date, latitude, longitude ) VALUES ('10133','2008-02-02 13:47:59',116.37659,39.85567);
+```
+
+Pode fazer essa mudança facilmente usando a função de buscar e substituir
+(find and replace), para todas as ocorrências nos scripts SQL.
+
+Também, há um [vídeo para exemplificar como adicionar o app no script](https://youtu.be/iwc9R7fF7P4).
+
+### Gerando seus endpoints
+
+Com Django, é possível integrar ferramentas como
+Django REST Framework para trabalhar na criação de uma API e sua
+[documentação oficial](https://www.django-rest-framework.org)
+é fundamental para orientá-lo na instalação e uso da ferramenta.
+
+Quando começar a documentar os endpoints
+de sua API, você deve usar [Swagger para REST Framework](https://drf-yasg.readthedocs.io/en/stable/readme.html)