APIs

Les APIs (Interfaces de Programmation d'Application) sont un ensemble de règles et de protocoles qui permettent à différentes applications logicielles de communiquer et d'interagir entre elles. Softyflow fournit un puissant constructeur d'API qui vous permet de créer des APIs personnalisées pour l'intégration et l'échange de données entre différentes plateformes, services et systèmes.

Créer une API​

Softyflow fournit une interface intuitive pour créer des APIs. Pour créer une nouvelle API, accédez à la section API située sur le côté gauche de l'interface du constructeur et fournissez un nom pour votre API.

L'interface de création d'API vous permet de configurer rapidement de nouvelles APIs en fournissant un nom unique et des paramètres de configuration initiaux.

Modes de Développement​

Softyflow offre deux approches de développement pour construire des APIs :

• Code Natif : Écrivez directement du code JavaScript pour une logique personnalisée
• Actions Prédéfinies : Utilisez le constructeur de workflow visuel avec des actions préconfigurées

Pour basculer entre les modes de développement, cliquez sur le bouton de bascule situé en haut au centre de l'interface.

Variables Système Disponibles​

Softyflow fournit plusieurs variables système qui sont automatiquement disponibles pendant le développement de l'API :

Configurer une API​

Pour accéder aux paramètres de configuration de l'API, cliquez sur le bouton d'icône de paramètres pour ouvrir le panneau de configuration. Ce panneau fournit un contrôle complet sur les propriétés et les permissions de votre API.

Le panneau de configuration vous permet de gérer les paramètres de l'API, les droits d'accès et de surveiller les journaux d'exécution.

Options de Configuration​

Paramètres Généraux​

Pendant le processus de configuration de l'API, les administrateurs peuvent :

• Nom de l'API : Modifier l'identifiant de l'API
• Droits d'Accès : Définir qui peut invoquer l'API
  • Sélectionner des groupes d'utilisateurs spécifiques
  • Définir comme publique pour un accès sans restriction

Informations API​

Le panneau de configuration affiche les détails essentiels de l'API :

Informations sur le Point de Terminaison :

• URL : L'URL complète du point de terminaison où l'API est accessible
• Method : Méthode HTTP utilisée (GET, POST, PUT, DELETE)
• Body : Structure de charge utile attendue et format de données

Variables Système :

• SF_body : Charge utile du corps de la requête
• SF_headers : En-têtes de la requête
• SF_query : Paramètres de requête de l'URL
• SF_mode : Environnement d'exécution actuel
• SF_initiator : Utilisateur qui a invoqué l'API

Journaux d'Exécution​

La section des journaux capture des informations détaillées sur l'exécution :

• User : Identité de l'utilisateur qui a invoqué l'API
• Launch Date : Horodatage de l'appel API
• Result : Résultat de l'exécution et données de réponse
• Details : Cliquez sur l'icône œil pour afficher les détails complets de l'exécution

Les journaux fournissent des informations précieuses pour le débogage, la surveillance de l'utilisation de l'API et le suivi des performances.

Tester et Exécuter les APIs​

Tester une API​

Softyflow fournit des capacités de test intégrées pendant la phase de développement. Vous pouvez définir des variables de test et valider le comportement de l'API avant le déploiement.

Définissez des variables de test au format JSON pour simuler de vraies requêtes API. Cela vous permet de valider la logique de votre API avec différents scénarios d'entrée.

Exécuter les Tests​

Cliquez sur le bouton œil pour exécuter le test de l'API. Les résultats seront affichés dans la section de sortie ci-dessous.

Le panneau de résultats affiche la réponse de l'API, le temps d'exécution et toutes les erreurs ou avertissements rencontrés pendant les tests.

Invoquer les APIs​

Softyflow fournit deux méthodes pour invoquer les APIs :

Méthode 1 : Utilisation de l'Action InvokeApi​

L'action InvokeApi fournit une approche visuelle sans code pour appeler des APIs depuis vos processus ou workflows.

Sélectionnez l'action InvokeApi depuis la palette d'actions pour commencer à configurer votre appel API.

Étapes de Configuration :

1. Sélectionner l'API : Choisissez l'API que vous souhaitez invoquer dans la liste déroulante

2. Nom de Variable : Spécifiez le nom de la variable où la réponse de l'API sera stockée

3. Corps de la Requête (optionnel) : Ajoutez des données de corps pour les requêtes POST/PUT

L'éditeur de corps vous permet de définir la charge utile au format JSON, avec prise en charge des variables dynamiques.

Méthode 2 : Utilisation d'Axios (Approche Basée sur le Code)​

Pour des cas d'utilisation avancés ou des intégrations externes, vous pouvez invoquer les APIs Softyflow en utilisant des clients HTTP standard comme Axios.

Exemple d'Implémentation :

// Define request body
let body = {
  email: "client1@gmail.com",
  userId: 12345,
};

// Construct API URL with mode parameter
let apiUrl =
  "https://softydev.softyflow.io/api/v1/api/6491696d1ef51ed2f7044b79?SF_mode=prod";

// Available modes: test, uat, prod

// Make POST request
let result = await axios.post(apiUrl, body);

// Access response data
console.log(result.data);

Considérations Clés :

• Paramètre de Mode : Spécifiez toujours SF_mode dans l'URL (test, uat, ou prod)
• Authentification : Incluez les en-têtes d'authentification si nécessaire
• Gestion des Erreurs : Implémentez des blocs try-catch pour une gestion robuste des erreurs
• Format de Réponse : Les réponses API sont généralement au format JSON

Exemple Avancé avec En-têtes :

try {
  let body = {
    email: "user@example.com",
    action: "getData",
  };

  let config = {
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_TOKEN",
    },
  };

  let apiUrl =
    "https://your-instance.softyflow.io/api/v1/api/YOUR_API_ID?SF_mode=prod";

  let response = await axios.post(apiUrl, body, config);

  // Process response
  return response.data;
} catch (error) {
  console.error("API call failed:", error);
  throw error;
}

Meilleures Pratiques​

Conception d'API​

• Nommage Clair : Utilisez des noms descriptifs qui indiquent le but de l'API
• Structure Cohérente : Maintenez des formats de requête/réponse uniformes
• Contrôle de Version : Envisagez le versionnage de l'API pour les changements futurs
• Documentation : Documentez les entrées, sorties et codes d'erreur attendus

Sécurité​

• Contrôle d'Accès : Restreignez l'accès à l'API aux utilisateurs/groupes autorisés
• Validation des Entrées : Validez toujours les données entrantes
• Messages d'Erreur : Évitez d'exposer des informations système sensibles
• Limitation de Débit : Implémentez une limitation pour les APIs de production

Tests​

• Tester Tous les Modes : Validez le comportement dans les modes test, UAT et production
• Cas Limites : Testez avec divers scénarios d'entrée
• Conditions d'Erreur : Vérifiez la gestion appropriée des erreurs
• Performance : Surveillez les temps de réponse et optimisez si nécessaire

Surveillance​

• Réviser les Journaux : Vérifiez régulièrement les journaux d'exécution pour détecter les erreurs
• Modèles d'Utilisation : Surveillez quelles APIs sont appelées le plus fréquemment
• Métriques de Performance : Suivez les temps de réponse et les taux de succès
• Systèmes d'Alerte : Configurez des notifications pour les échecs critiques

Dépannage​

Problèmes Courants​

API qui ne Répond Pas​

Problème : Les appels API ne retournent aucune réponse ou expirent

Solutions :

• Vérifiez que l'URL de l'API est correcte
• Vérifiez si l'API est activée dans le mode spécifié
• Assurez-vous de la connectivité réseau à l'instance Softyflow
• Consultez les journaux d'exécution pour les détails d'erreur

Erreurs d'Authentification​

Problème : Réponses "Non autorisé" ou "Interdit"

Solutions :

• Vérifiez que l'utilisateur dispose des droits d'accès appropriés
• Vérifiez si l'API est définie comme publique si nécessaire
• Confirmez que les en-têtes d'authentification sont corrects
• Vérifiez les attributions de rôles dans la configuration

Format de Données Incorrect​

Problème : L'API reçoit ou retourne des données inattendues

Solutions :

• Validez que le corps de la requête correspond au schéma attendu
• Vérifiez l'utilisation des variables SF_body, SF_query
• Examinez la logique de l'API pour une transformation appropriée des données
• Testez avec des données d'exemple en mode test

Problèmes de Performance​

Problème : Temps de réponse lents de l'API

Solutions :

• Optimisez les requêtes de base de données dans la logique de l'API
• Réduisez le traitement de données inutile
• Envisagez la mise en cache des données fréquemment accédées
• Surveillez et limitez les exécutions simultanées

Pour une assistance supplémentaire, consultez les journaux d'exécution et examinez les paramètres de configuration de l'API.