Dans un projet Apidog, les points d'accès (endpoints) sont gérés selon une structure hiérarchique de Module → Dossier → Points d'accès.
- Les Modules représentent des fichiers OpenAPI indépendants, généralement regroupés par domaine d'activité ou par service.
- Les Dossiers organisent les points d'accès par fonctionnalité au sein d'un module.
- Les Points d'accès sont les spécifications OpenAPI ou les définitions d'API réelles.
Comprendre cette structure est essentiel pour organiser efficacement vos API.
Voici un exemple de hiérarchie simple :
Projet Apidog
│
├── Module : Service Utilisateur (divisé par domaine d'activité ou service)
│ │
│ ├── Dossier : Authentification Utilisateur (catégorie de fonctionnalité)
│ │ │
│ │ ├── Point d'accès : POST /login (Connexion)
│ │ └── Point d'accès : POST /register (Inscription)
│ │
│ └── Dossier : Informations Utilisateur
│ │
│ └── Point d'accès : GET /users/{id} (Obtenir les informations utilisateur)
│
└── Module : Service de Commande
│
├── Dossier : Gestion des Commandes
│ │
│ ├── Point d'accès : POST /orders (Créer une commande)
│ └── Point d'accès : GET /orders/{id} (Obtenir les détails de la commande)
│
└── Dossier : Paiement
│
└── Point d'accès : POST /payment/submit (Soumettre le paiement)Comprendre les Modules dans Apidog
Après avoir compris la hiérarchie du projet, la question suivante est : Chaque projet a-t-il besoin de modules ? Quand faut-il en créer un nouveau ?
Lorsque vous créez un nouveau projet, Apidog génère automatiquement un module par défaut. Si votre projet ne contient qu'un seul service backend ou un petit ensemble de points d'accès, ce module par défaut est généralement suffisant. Cependant, si vous devez gérer plusieurs services API distincts, vous pouvez créer un module séparé pour chacun d'eux.
Par exemple, un backend de projet peut inclure des services tels que Utilisateur, Produit, Commande et Logistique – chacun étant responsable d'un domaine spécifique et souvent déployé sur des URL de service différentes. Dans ce cas, il est recommandé de créer des modules individuels pour ces services afin de gérer leurs points d'accès de manière indépendante.
Vous pouvez créer un module en cliquant sur le bouton + au-dessus de l'arborescence des dossiers et en sélectionnant Module.
Une fois créé, il apparaît dans l'arborescence du projet à gauche, aux côtés des autres, avec son propre espace pour les dossiers et les points d'accès. Vous pouvez librement ajouter des points d'accès et des dossiers au sein de chaque module.
Les modules sont indépendants les uns des autres, chacun ayant ses propres points d'accès, schémas, composants et variables de module. Cependant, les schémas peuvent être référencés entre les modules. De plus, les paramètres au niveau du projet, tels que les variables d'environnement, les connexions à la base de données et les scripts communs, sont accessibles à tous les modules.
Chaque module correspond à un fichier de spécification OpenAPI complet. Lors de l'exportation de votre projet, les fichiers OpenAPI sont générés par module.
Comprendre les Dossiers au sein d'un Module
Après avoir créé vos modules, l'étape suivante consiste à planifier la structure des points d'accès qu'ils contiennent.
Chaque module commence par un dossier racine qui contient tous les sous-dossiers et les points d'accès.
Vous pouvez créer des dossiers directement sous la racine ou les imbriquer dans d'autres dossiers existants.
Lors de la conception de la structure des dossiers, tenez compte de la complexité du module. Pour un module avec seulement quelques points d'accès, un simple dossier à niveau unique organisé par fonction est généralement suffisant. Mais pour des modules plus complexes, il est préférable de créer des dossiers multi-niveaux bien structurés pour que tout reste organisé et facile à naviguer.
Par exemple, dans un module Service Utilisateur, vous pourriez avoir des dossiers de premier niveau tels que :
- Authentification Utilisateur (pour les points d'accès de connexion, d'inscription, de réinitialisation de mot de passe)
- Informations Utilisateur
- Contrôle d'Accès
Si un dossier devient trop volumineux ou logiquement indépendant, vous pouvez le convertir en un module autonome.
Cliquez sur l'icône ... à côté du nom du dossier et sélectionnez ...Plus > Convertir en un nouveau Module. Cela permet de maintenir la structure de votre projet bien organisée à mesure qu'il évolue.
Gestion de l'Environnement et Configuration pour un Module
Outre les points d'accès structurés, chaque module correspond généralement à une adresse de service ou un environnement de déploiement différent. Vous pouvez les configurer facilement dans la Gestion de l'Environnement.
Dans les paramètres de gestion de l'environnement, l'URL de base de chaque module peut être configurée séparément. Par exemple, dans un Environnement de Test :
- Service Utilisateur →
http://user-service:8001 - Service de Commande →
http://order-service:8002
Lors du changement d'environnement, Apidog met automatiquement à jour l'URL de base de chaque module. Par exemple, lors du passage de l'environnement de développement à celui de test, l'URL de base du module de service utilisateur passera de http://localhost:8001 à http://user-service:8001, et l'URL de base du module de service de commande passera de http://localhost:8002 à http://order-service:8002.
Les variables d'environnement sont partagées entre tous les modules et sont idéales pour stocker des paramètres qui diffèrent entre les environnements. En revanche, les variables de module sont propres à chaque module – par exemple, leurs propres clés API ou jetons – et peuvent être utilisées dans n'importe quel point d'accès de ce module.
Gérer et Réutiliser les Schémas
Une gestion efficace des schémas permet d'éviter la duplication et d'assurer la cohérence entre les modules.
Chaque module possède sa propre section de gestion des schémas, où vous pouvez définir et maintenir des structures de données liées à l'entreprise. Ces schémas peuvent être réutilisés au sein du module ou référencés par d'autres.
Par exemple, le module Service Utilisateur définit les schémas liés aux utilisateurs. Le module Service de Commande définit les schémas liés aux commandes. Si le Service de Commande doit référencer des informations utilisateur, il peut simplement réutiliser le schéma du Service Utilisateur – pas besoin de le recréer.
De Postman à Apidog : Organiser les Collections et Points d'accès Importés
Si votre équipe utilisait auparavant Postman, vous pouvez facilement migrer les collections et points d'accès existants vers Apidog.
Pendant l'importation :
- Chaque Collection Postman devient un Module.
- Les structures de dossiers sont automatiquement mappées.
- Les points d'accès et les schémas sont préservés.
Cela vous permet de conserver votre structure d'API familière tout en profitant du système modulaire d'Apidog.
Conclusion
En définissant des modules clairs, en organisant les dossiers et en réutilisant les schémas, vous pouvez maintenir vos projets Apidog propres, évolutifs et faciles à collaborer.
La conception modulaire d'Apidog aide les équipes à travailler plus rapidement, à éviter la confusion et à gérer des API complexes plus efficacement – de la conception à la documentation en passant par les tests.