Ejemplo de un API REST realizada con TypeScript. Autenticación, CRUD, transferencia de ficheros. Modos de trabajo en: Memoria, MongoDB o MariaDB. Despliegue en Docker y test con Jest.
- TypeScrip API REST
El proyecto consiste en que tengas un ejemplo de API REST pero realizada con TypeScript con el objetivo de mejorar con tipos tus desarrollos. Además propone el uso de ficheros, autenticación y autorización mediante JWT. Tiene tres modos de uso Memoria, con MongoDB (NoSQL) y MariaDB (SQL).
Acceso desde: http://localhost:8000.
El diseño de esta API REST se corresponde con el patrón Servidor->Enrutador->Controlador->Modelo. El Servidor escucha en un puesto diversas peticiones. Las procesa según su ruta o punto de entrada y se las pasa al Enrutador. El Enrutador analiza la petición dependiendo de la ruta y se la pasa al Controlador correspondiente a dicha ruta que ejecutará el método indicado. El Controlador realiza el método indicado según la ruta consultando los modelos y almacenamiento para ello. El Modelo es la estructuración de los datos a tratar.
En todo momento se ofrece información de la petición en base a los códigos de estado HTTP.
Este proyecto está basado en dos modos de funcionamiento en la url: http://localhost:8000.
- Memoria: Usando almacenamiento en memoria. Lo tienes en la rama Memoria.
- MogoDB: Usando almacenamiento en MogoDB. Lo tienes en la rama MongoDB.
- MariaDB: Usando almacenamiento en MariaDB. Lo tienes en la rama MariaDB.
Se ha implementado un sistema de atenticación y autorización basado en JWT y aplicando un Middleware para analizar si el usuario puede entrar a un recurso, ya sea por que está autenticado para ello (auth), o tiene permisos dependiendo su rol (grant), o dicho recurso le pertenece, si tenemos datos que los relacionen (owner). Se ha jugado con distintas políticas dependiendo del recurso y se puede adaptar a las distintas necesidades del problema. En el código podrás ver distintas soluciones con middleware o dentro del controlador.
Se ha implemedo dos sistemas de validación de campos según los requisitos de los tipos de datos. Por un lado un middleware de validación y por otro, si no queremos hacerlo de esta manera, con funciones auxiliares en el propio controlador.
Los Endpoints para conectarse y consumir esta api rest, empiezan siempre por /api/vx/recurso, donde x es a versión de esta api, y recurso es el recurso a consumir, por ejemplo /api/v1/juegos desde http://localhost:8000.
| Método | Recurso | Auten/Autor. | Descripción |
|---|---|---|---|
| POST | user/register | -- | Registra un usuario/a |
| POST | user/login | -- | Se indentifica en el sistema y obtiene token de acceso |
| GET | /user/id | auth | Obtiene los datos del usuario/a con id indicado si pertenece a él/ella |
| PUT | /user/id | auth | Modifica los datos del usuario/a con id indicado si pertenecen a él/ella |
| DELETE | /user/id | auth | Elimina el usuario/a con id indicado si pertenecen a él/ella |
| GET | /juegos | -- | Obtiene todos las juegos |
| GET | /juegos/id | -- | Obtiene el juego con el id indicado |
| POST | /juegos | auth | Añade el juego |
| PUT | /juegos/id | auth, owner | Modifica el juego con el id indicado si pertenece al usuario/a |
| DELETE | /juegos/id | auth | Elimina el juego con el id indicado si pertenece al usuario/a |
| GET | /files | auth, grant('ADMIN') | Obtiene todos los ficheros. Solo Admin |
| GET | /files/id | auth | Obtiene datos del fichero con el id indicado si pertenece al usuario/a |
| GET | /files/download/id | -- | Descarga el fichero con el id indicado |
| POST | /files | auth | Añade el fichero |
| PUT | /files/id | auth | Modifica el fichero con el id indicado si pertenece al usuario/a |
| DELETE | /files/id | auth | Elimina el fichero con el id indicado si pertenece al usuario/a |
Se ha usado la librería Jest, con TypeScript para realizar los test siguiendo un enfoque TDD y Supertest para testear las peticiones HTTP a la API.
Es importante que ajustes el fichero .env o que hagas dos de ellos según sea desarrollo o producción y con ello ajustes el docker.compose o la forma de lanzar todo.
Tareas que podemos ejecutar dentro de nuestra aplicación.
Te recomiendo leer el fichero package.json:
- npm install: para instalar las dependencias.
- npm start (npm run start): ejecuta el entorno producción.
- npm run dev: compila el TypeScript en busca de errores.
- npm run dev:run: ejecuta el código en podo desarrollo.
- npm run dev:watch: ejecuta el código en modo observador.
- npm run build: construye la versión de distribución/producción (en el directorio build).
- npm test (npm run test): ejecuta todos los test.
- npm run test:coverage: obtiene el índice de cobertura del código.
- npm run test:watch: realiza los test mientras modificas el código.
- npm run test:sec: realiza los test de manera secuencial pues puede dar error al cerrar el servidor.
- npm run docker:mongo: incia sel servidor local MongoDB y Mongo-Express en desarrollo (si estás en su rama)
- npm run docker:mariadb: incia sel servidor local MariaDB y Adminer en desarrollo (Si estás en su rama)
- npm run docker:clean: limpia todos lso dockers
- npm run docker:deploy: lanza el fichero docker-compose para producciónEl desppliegue dependerá de la rama.
Esta API se puede desplegar con Docker si te gusta ya sea a través de su Dockerfile o a otraves de Docker Hub, para ello:
- docker build -t joseluisgs/joseluisgs/ts-api-rest .
- docker run -it -p 8000:8000 --rm --name ts-api-rest-1 joseluisgs/ts-api-restSe ha optimizado el uso de contenedores usando Docker Compose y acceder desde http://localhost:8000 . De hecho el almacenamiento se ha implementado en un contenedor de tipo Volumen tanto para la API como para MongoDB. Además permite consultar con Mongo-Empress (http://localhost:8081/).
- docker-compose up -dDisponible en: https://hub.docker.com/r/joseluisgs/ts-api-rest
Las versiones de almacenamiento con BB.DD dependerán de cada rama
Para probar y hacer pruebas locales con MongoDB puedes usar el fichero mongo.sh, o simplemente ejecutar el compose de MongoDB y Mongo-Express:
- docker-compose -f mongo-compose.yml up -dEsta apliación web te permite manejar MongoDB a partir de una interfaz web en: http://localhost:8081/
Para probar y hacer pruebas locales con MariaDB puedes usar el fichero mariadb.sh, o simplemente ejecutar el compose de MariaDB y Adminer:
- docker-compose -f maria-compose.yml up -dEsta apliación web te permite manejar MariaDB a partir de una interfaz web en: http://localhost:8080/
Puedes probar y consumir la API usando por ejemplo Postman y su fichero.Deberás completar las llamadas que hagan uso de los tokens.
Codificado con 💖 por José Luis González Sánchez
Este proyecto esta licenciado bajo licencia MIT, si desea saber más, visite el fichero LICENSE para su uso docente y educativo.