paul-schuhm / starterpack-api-nodejs

Un kit de développement dockerisé d'une application web Node.js/Express.js pour développer une web API RESTful (à but pédagogique)

Starter pack: RESTful web API avec Node.js, Express.js, MySQL et Adminer

Un starter pack dockerisé d'une application web node.js pour développer une web API RESTful. L'API vient avec un service de base de données relationnelles (MySQL) et un client graphique (Adminer).

• Starter pack: RESTful web API avec Node.js, Express.js, MySQL et Adminer
  • Prérequis
  • Lancer le projet avec Compose
  • Tester
    • API
    • Base de données
    • Client graphique Adminer pour la base de données MySQL
  • Base de données
    • ORM
  • Debuger lors du développement
    • En ligne de commande avec docker
    • Avec Visual Studio Code
  • Documentation de l'API avec Swagger
  • Installer et servir de nouvelles dépendances
  • Arrêter le projet
  • Améliorations
  • Conseils pour le développement
  • Modules Node.Js notables
  • Autorisation avec JWT
  • Ressources
    • Docker
    • Express
    • Swagger
    • SGBDR
    • Adminer

Prérequis

• installer node.js
• installer Docker et Compose
• clôner le dépôt et se placer à la racine du projet

N'oubliez pas de supprimer le dossier .git si vous désirez créer votre propre dépôt à partir des sources

rm -R .git
git init

Lancer le projet avec Compose

Dupliquer le fichier .env.dist

cp .env.dist .env

Vous pouvez modifier les variables d'environnement si vous le souhaitez (des valeurs par défaut sont fournies)

Installer les dépendances de l'application node et générer la doc swagger

pushd api
npm install
npm run swagger-autogen
popd

Démarrer le projet

docker-compose up -d

Tester

API

Se rendre à l'URL localhost:5001, ou tester (avec curl)

# Web humain (HTML)
curl --include localhost:5001
# API (JSON)
curl localhost:5001

Base de données

Avec le client mysql (depuis la machine hôte) :

mysql -uroot -proot -Dmydb -h127.0.0.1 -P5002

Puis, dans le repl MySQL (session ouverte avec la commande précédente)

-- Lister les utilisateurs MySQL
SELECT user FROM mysql.user;
-- Lister les users dans la base de départ
SELECT * FROM User;

Pour exécuter un script SQL en Batch mode

mysql -uroot -p -Dmydb -h127.0.0.1 -P5002 < script.sql

Penser à modifier la valeur du port si vous l'avez changé dans le .env

Machine hôte : la machine sur laquelle s’exécute les conteneurs Docker, votre machine

Client graphique Adminer pour la base de données MySQL

Le starterpack vient avec Adminer, un gestionnaire de base de données à interface graphique, simple et puissant.

Se rendre sur l'URL http://localhost:5003 (par défaut) et se connecter avec les credentials root (login root et mot de passe root par défaut), ou ceux de l'utilisateur (user et password par défaut)

Base de données

La base de données vient avec deux utilisateurs par défaut :

• root (administrateur), mot de passe : root
• user (utilisateur lambda), mot de passe : password

Pour accéder à la base de données :

• Depuis un autre conteneur (Node.js, Adminer) : host est db, le nom du service sur le réseau Docker
• Depuis la machine hôte (une application node, PHP exécutée sur votre machine, etc.) : host est localhost ou 127.0.0.1. Préférer utiliser l'adresse IP 127.0.0.1 plutôt que son alias localhost pour faire référence à votre machine (interface réseau qui) afin éviter des potentiels conflits de configuration avec le fichier socket (interface de connexion sous forme de fichier sur les systèmes UNIX) du serveur MySQL installé sur votre machine hôte (si c'est le cas).

ORM

Pour interagir avec la base de données SQL, nous pouvons utiliser l'ORM Sequelize

Debuger lors du développement

Inspecter les logs du conteneur Docker qui contiennent tout ce qui est écrit sur la sortie standard (avec console.log()). Les sources de l'application Node.js sont watchées, donc à chaque modification d'un fichier source l'application redémarre pour les prendre en compte automatiquement

En ligne de commande avec docker

#Suivi en temps réel des logs
docker logs -f demo-rest-api-api 

Avec Visual Studio Code

• Installer l'extension officielle Docker
• Click droit sur le conteneur demo-rest-api-api qui héberge l'application Node.js, puis View Logs

Documentation de l'API avec Swagger

Générer automatiquement la documentation de vos routes avec le module Swagger

Placez-vous dans le dossier api puis

node swagger.js

ou

npm run swagger-autogen

Se rendre à l'URL /doc pour accéder à l'UI de Swagger

Installer et servir de nouvelles dépendances

A la racine de l'application, installer les dépendances désirées via npm

pushd api
npm install <votre paquet>
popd

Arrêter le projet

docker-compose down

Améliorations

Se débarrasser des étapes avant la dockerisation du projet (installation des dépendances). Le problème réside dans le fait que le volume monté écrase les fichiers lors de la construction de l'image. On ne peut donc pas en l'état simplement les déplacer dans l'image Docker.

Conseils pour le développement

• Ouvrez une connexion MySQL pendant votre développement pour tester vos requêtes avant de les intégrer dans voter code
• Utiliser cURL pour tester rapidement vos requêtes HTTP. Ouvrez par exemple deux terminaux, l'un avec cURL et l'autre avec les logs de l'API pour débuger facilement votre système
• Installer le module dotenv pour placer le DSN (informations de connexion à la base) en dehors du code
• Pour tester des enchaînements de requêtes, écrivez un script SQL capable de remettre la base dans un état initial et contenant les requêtes à tester et un autre script pour effectuer les requêtes HTTP, et exécuter le tout en une commande

Modules Node.Js notables

• bodyParser, un parser du corps de requête pour les applications node. On s'en sert pour parser les représentations envoyées par le client dans nos contrôleurs avec l'instruction app.use(bodyParser.urlencoded({ extended: true }));
• jsonwebtoken, une implémentation javascript du standard JSON Web Token, voir RFC 7519
• cors, un module middleware pour gérer la politique CORS (Cross Origin Resource Sharing)
• mysql2, un client MySQL pour Node.js qui utilise l'API des promesses (contrairement à son prédécesseur mysql)

Autorisation avec JWT

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties (Source: RFC7519)

Pour autoriser (et donc authentifier) l'utilisateur à interagir avec les ressources, on utilise un JSON Web Token. Implémentée dans le projet avec le package jsonwebtoken

Ressources

Docker

• Image Docker Node
• Image Docker MySQL
• Image Docker Adminer
• Dockerizing a Node.js web app

Express

• Générateur d’applications Express, générer un projet pour démarrer
• Routage, la documentation sur le routage d'Express
• Pug, moteur de templates javascript installé par défaut avec Express
• API JSON Web Token Authentication (JWT) sur Express.js, un bon tutoriel pour mettre en place des routes protégées par Json Web Token

Swagger

• Swagger UI, documenter une web API RESTful (même si elle devrait être par définition auto-documentée et auto-descriptive)
• Swagger UI Express, module node.js pour générer la documentation de l'API avec Express
• Swagger auto-gen, module de génération automatique de la documentation de l'API dans une application node.js/Express. Voir notamment la documentation pour documenter automatiquement les endpoints (résumé, description, paramètres)
• Swagger auto-gen: décrire des paramètres de formulaire POST
• OpenAPI Specification, un standard de description d'une web API comptabile avec REST

SGBDR

• MySQL Docker Image, quick reference
• mysql2, le driver node.js pour le SGBDR MySQL qui implémente l'API des promesses (contrairement à mysql)
• Sequelize, Getting Started, Sequelize, un ORM pour Node.js

Adminer

• Adminer