magic-api est un framework de développement rapide d'API basé sur Java. Il permet de définir des points d'extrémité (endpoints) via une interface utilisateur graphique, générant automatiquement les correspondants HTTP. Cela élimine le besoin de créer manuellement les classes Java habituelles comme les Controllers, Services, DAO, et les fichiers XML ou VO.

Intégration dans un projet Spring Boot

1. Ajout des dépendances

Intégrez les artefacts nécessaires dans votre fichier pom.xml.

<!-- magic-api pour le développement rapide d'API -->
<dependency>
    <groupId>org.ssssssss</groupId>
    <artifactId>magic-api-spring-boot-starter</artifactId>
    <version>2.0.1</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.27</version>
</dependency>

2. Configuration de l'application

Définissez les propriétés dans application.yml.

server:
  port: 8080
spring:
  datasource:
    driver-class-name: com.mysql.jdbc.Driver
    url: jdbc:mysql://localhost:3306/bdd_magic_api?useUnicode=true&characterEncoding=utf-8&serverTimezone=Europe/Paris
    username: identifiant
    password: mot_de_passe
magic-api:
  web: /console-api
  resource:
    type: file
    location: /chemin/vers/fichiers-api
  sql-column-case: camel

3. Initialisation de la base de données

Créez une base de données MySQL nommée bdd_magic_api.

4. Lancemnet et accès à l'interface

Démarrez l'application Spring Boot. L'interface d'administration des API est accessible à l'adresse : http://localhost:8080/console-api.

Écriture des scripts d'API

Création d'un point d'extrémité

Organisez les API en groupes. Pour une opération de création, utilisez le script suivant et configurez une méthode POST sur le chemin /creer avec un corps de requête JSON.

// Récupération directe des données depuis le corps de la requête
return db.table('articles_catalogue').insert(donnees);

Recherche par identifiant

Pour obtenir un enregistrement par son ID, configurez un endpoint GET sur /detail/{identifiant}.

// Récupération d'une variable de chemin
return db.table('articles_catalogue')
    .where()
    .eq('id', chemin.identifiant)
    .selectOne();

Mise à jour d'un enregistrement

Pour modifier un enregistrement, utilisez une requête POST vers /modifier avec les nouvelles valeurs dans le corps.

return db.table('articles_catalogue')
    .primary('id', donnees.id)
    .update(donnees);

Liste paginée

Pour obtenir une liste paginée via un endpoint GET sur /lister, le script est minimal grâce à la configuration préétablie.

return db.table('articles_catalogue').page();

Suppression

La suppression s'effectue via une opération de type mise à jour. Configurez un POST sur /supprimer/{identifiant}.

// Exécution d'une requête SQL brute paramétrée
return db.execute('DELETE FROM articles_catalogue WHERE id=#{identifiant}');

Validation des entrées

Le module assert permet de vérifier les paramètres avant l'exécution du code métier.

import assert; // Chargement du module de vérification
// L'arrêt de l'exécution se produit en cas d'échec
assert.notEmpty(donnees.nom, 400, 'Le champ nom est obligatoire !');
assert.notEmpty(donnees.initiale, 400, 'Le champ initiale est obligatoire !');
return db.table('articles_catalogue').insert(donnees);

Transformation des données de sortie

Il est possible de remodeler la réponse de l'API, par exemple pour convertir des valeeurs et sélectionner des champs spécifiques.

var listeResultats = db.table('articles_catalogue').select();
return listeResultats.map((element) => {
    designation: element.nom,
    code_initiale: element.initiale,
    etat_affichage: element.statutAffichage ? 'Masqué' : 'Visible'
});

Gestion des transactions

magic-api prend en charge les transactions via la méthode db.transaction().

import assert;
var resultat = db.transaction(() => {
    var enregistrement = db.table('articles_catalogue')
        .where().eq('id', donnees.id)
        .selectOne();
    assert.notNull(enregistrement, 404, 'Aucun enregistrement trouvé !');
    db.table('articles_catalogue').primary('id', donnees.id).update(donnees);
    return 'Mise à jour réussie';
});
return resultat;

Intégration de la documentation Swagger

Après avoir ajouté les dépendances Swagger appropriées, configurez la section correspondante dans application.yml.

magic-api:
  swagger-config:
    name: Documentation API du projet
    title: Spécification API REST
    description: Documentation technique des points d'accès générés par magic-api.
    version: 1.0.0
    location: /v2/api-docs/magic-api/swagger.json

Avantages du framework

• Développement accéléré : Supprime la création de couches Java (Controller, Service, DAO). La définition se fait visuellement.
• Compilation dynamique : Basé sur le moteur magic-script, les modifications sont prises en compte sans redémarrage.
• Multi-sources de données : Supporte la configuration de plusieurs bases de données à l'exécution.
• Compatibilité large : Fonctionne avec toute base de données compatible JDBC (MySQL, PostgreSQL, Oracle, etc.).
• Personnalisation étendue : Permet d'ajouter des utilitaires, des modules, d'étendre les types et de configurer des intercepteurs.

Limitations connues

• Logique métier complexe : Peu adapté pour des algorithmes métier très élaborés, où un code Java structuré reste préférable.
• Scalabilité : Conçu pour la rapidité de développement sur des projets de petite à moyenne taille. La gestion de projets d'entreprise très larges avec des exigences de modularité et de performance strictes peut nécessiter des approches complémentaires.