Dans un article précédent, nous avons vu comment créer une API Rest en Javascript. Néanmoins, cela peut paraître long et redondant.
Heureusement, il existe des outils (ou Frameworks) nous permettant de faciliter la création de nos API Rest.
Voici donc quelques exemples d’outils que vous pouvez utiliser dans la création, suivi d'un exemple en Express !
Spring Boot
Spring Boot est un framework de développement Java, permettant de créer des API Rest Java en respectant le modèle MVC (Modèle View Controller)
👉 https://spring.io/projects/spring-boot
Express
Express est un framework basé sur Node JS et écrit en Javascript, permettant de configurer des middlewares pour répondre aux requêtes HTTP.
👉 https://expressjs.com/fr/
Nest
Nest est un framework Node JS complet basé sur Express et écrit en Typescript. Inspiré de Angular, il impose une structure bien précise pour développer des applications.
👉 https://nestjs.com/
Symfony
Symfony est un framework écrit en PHP, permettant de développer des applications web évolutives ou de créer des sites dynamiques.
👉 https://symfony.com/
Allons plus loin : un exemple d’implémentation avec Express
Maintenant que vous connaissez certains outils, pourquoi ne pas mettre en pratique ?
Dans l’exemple suivant, nous allons créer une API Rest avec Express puis la documenter à l’aide de Swagger.
Les pré-requis pour implémenter :
Pour commencer, naviguez dans un nouveau dossier puis lancez la commande npm init afin d’initialiser le projet.
On installe ensuite les dépendances suivantes à l’aide de npm :
npm install express lowdb nanoid cors morgan swagger-jsdoc swagger-ui-express
**lowdb** -> utilisé comme store pour nos données
**nanoid** -> pour générer un identifiant unique
Enfin, rajoutez “type”=”module” dans le package.json
A la fin de l’installation, le fichier devrait ressembler à ceci.
{
"name": "test",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \\"Error: no test specified\\" && exit 1"
},
"type": "module",
"author": "",
"license": "ISC",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.18.2",
"lowdb": "^5.0.5",
"morgan": "^1.10.0",
"nanoid": "^4.0.0",
"swagger-jsdoc": "^6.2.7",
"swagger-ui-express": "^4.6.0"
}
}Ensuite, créez un fichier index.js puis ajoutez le code suivant afin d’initialiser le serveur :
//importe et crée l'application express
import express from "express";
import morgan from "morgan";
import cors from "cors";
import { Low, JSONFile } from "lowdb";
//initialise la base de stockage des données
const adapter = new JSONFile("db.json");
const db = new Low(adapter);
await db.read();
db.data ||= { orders: [] };
const app = express();
app.db = db.data;
app.use(cors());
app.use(express.json());
//démarre le serveur sur le port indiqué
app.listen(4000, () => {
console.log(`Server is running on 4000`);
});Maintenant, vérifions que notre code fonctionne en entrant node index.js dans le terminal. Server is running on 4000 s’affiche.
Nous allons ensuite lier une base de données à notre serveur sous la forme d’un fichier JSON.
Pour cela, à la racine, créez le fichier db.json et ajoutez le code suivant :
{
"orders": [
{
"id": "5403d7f7c19e51e2ea3c02c3",
"total": 26,
"items": [
{
"id": "5403d655c19e51e2ea3c02c0",
"name": "Entrecôte",
"price": 16
},
{
"id": "5403d655c19e51e2ea3c02c0",
"name": "Salade",
"price": 10
}
]
},
{
"id": "lfjdsi2978zjbhd",
"total": 15,
"items": [
{
"id": "5403d655c19e51e2ea3c02c0",
"name": "Pâtes",
"price": 15
}
]
}
]
}Puis dans le fichier index.js remplacez const app = express(); avec le code suivant :
const adapter = new JSONFile("db.json");
const db = new Low(adapter);
await db.read();
db.data ||= { orders: [] };
const app = express();
app.db = db.data;Enfin, nous allons créer nos routes d’API.
Créez un fichier orders.js à la racine du projet et ajoutez le code suivant :
import express from "express";
import { nanoid } from "nanoid";
const router = express.Router();
//retourne la liste des commandes
router.get("/", (req, res) => {
const orders = req.app.db;
res.send(orders);
});
//ajoute une nouvelle commande
router.post("/", (req, res) => {
try {
const order = {
id: nanoid(8),
...req.body,
};
const newArrayOfOrders = req.app.db.orders.concat(order);
res.send(newArrayOfOrders);
} catch (err) {
return res.status(500).send(err);
}
});
//supprime une commande
router.delete("/:id", (req, res) => {
req.app.db.orders.find((order) => order.id !== req.params.id);
res.sendStatus(200);
});
export default router;Puis dans index.js, importez le router, puis ajoutez const app = express(); juste avant app.listen(...)
Relancez le router pour voir les modifications.
Arrivé à ce stade-ci, nous avons créé une API Rest avec Express.
Pour la tester, nous allons passer à la documentation.
Dans index.js ajoutez les imports suivants :
import swaggerUI from "swagger-ui-express";
import swaggerJsDoc from "swagger-jsdoc";
Puis ajoutez ceci au dessus de app.listen
const options = {
definition: {
openapi: "3.0.0",
info: {
title: "Library API",
version: "1.0.0",
description: "A simple express",
},
servers: [
{
url: "<http://localhost:4000>",
},
],
},
apis: ["./orders.js"],
};
const specs = swaggerJsDoc(options);
app.use("/api-docs", swaggerUI.serve, swaggerUI.setup(specs));Enfin dans orders.js, ajoutez les commentaires suivants :
/**
* @swagger
* components:
* schemas:
* order:
* type: object
* properties:
* id:
* type: string
* description: The auto-generated id of the order
* total:
* type: number
* description: The total of the book
* items:
* type: [object]
* properties:
* id:
* type: string
* description: The auto-generated id of the order item
* name:
* type: string
* description: The name of the order item
* price:
* type: number
* description: The price of the order item
* example:
* id: sknfdkl
* total: 10
* items: [{id: dkjzanf, name: saumon, price: 10}]
*
*/
...
Méthode GET
...
/**
* @swagger
* tags:
* name: Orders
* description: The orders managing API
*/
/**
* @swagger
* /orders:
* get:
* summary: Returns the list of all the orders
* tags: [Orders]
* responses:
* 200:
* description: The list of the orders
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/order'
*/
...
Méthode POST
...
/**
* @swagger
* /orders:
* post:
* summary: Create a new order
* tags: [Orders]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/order'
* responses:
* 200:
* description: The order was successfully created
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/order'
* 500:
* description: Some server error
*/
...
Méthode DELETE
...
/**
* @swagger
* /orders/{id}:
* delete:
* summary: Remove the order by id
* tags: [Orders]
* parameters:
* - in: path
* name: id
* schema:
* type: string
* required: true
* description: The order id
*
* responses:
* 200:
* description: The order was deleted
* 404:
* description: The order was not found
*/
...
Conclusion
Vous voilà à présent capable de créer une API Rest documentée avec Express !
Bien entendu, chaque framework présente ses avantages et ses inconvénients. Express est connu pour être flexible et facile à prendre en main, mais difficile à maintenir, car il fournit peu de restrictions (programmation spaghetti).
Le framework est cependant utilisé par de nombreuses compagnies telles que Twitter, Blablacar ou encore Trustpilot.
