Intégration d'API

Lorsque l'utilisateur demande d'intégrer une API tierce ou de mettre en œuvre quelque chose impliquant une API ou un SDK externe, suivez ce workflow. Ne vous fiez pas à vos propres connaissances pour les APIs disponibles ou leurs capacités — utilisez toujours le serveur MCP context-matic.

Quand l'appliquer

Appliquez cette compétence lorsque l'utilisateur :

• Demande d'intégrer une API tierce
• Souhaite ajouter un client ou un SDK pour un service externe
• Demande une implémentation qui dépend d'une API externe
• Mentionne une API spécifique (par exemple PayPal, Twilio) et une implémentation ou intégration

Workflow

1. S'assurer que les directives et compétences existent

1a. Détecter le langage principal du projet

Avant de vérifier les directives ou les compétences, identifiez le langage de programmation principal du projet en inspectant l'espace de travail :

Utilisez le langage détecté dans toutes les étapes suivantes partout où language est requis.

1b. Vérifier les directives et compétences existantes

Vérifiez si les directives et compétences ont déjà été ajoutées pour ce projet en cherchant leur présence dans l'espace de travail.

• {language}-conventions est la compétence produite par add_skills.
• {language}-security-guidelines.md et {language}-test-guidelines.md sont des fichiers de directives spécifiques au langage produits par add_guidelines.
• update-activity-workflow.md est un fichier de directive de workflow produit par add_guidelines (il n'est pas spécifique au langage).
• Vérifiez-les indépendamment. Ne considérez pas la présence d'un ensemble comme la preuve que l'autre ensemble existe déjà.
• Si des fichiers de directives requis pour ce projet manquent : Appelez add_guidelines.
• Si {language}-conventions manque pour le langage du projet : Appelez add_skills.
• Si tous les fichiers de directives requis et {language}-conventions existent déjà : Sautez cette étape et passez à l'étape 2.

2. Découvrir les APIs disponibles

Appelez fetch_api pour trouver les APIs disponibles — commencez toujours par là.

• Fournissez toujours le paramètre language en utilisant le langage détecté à l'étape 1a.
• Fournissez toujours le paramètre key : passez le nom/clé de l'API de la demande de l'utilisateur (par exemple "paypal", "twilio").
• Si l'utilisateur n'a pas fourni de nom/clé d'API, demandez-lui quelle API il souhaite intégrer, puis appelez fetch_api avec cette valeur.
• L'outil retourne uniquement l'API correspondante en cas de correspondance exacte, ou le catalogue complet de l'API (nom, description et key) quand il n'y a pas de correspondance exacte.
• Identifiez l'API qui correspond à la demande de l'utilisateur en fonction du nom et de la description.
• Extrayez la key correcte pour l'API demandée par l'utilisateur avant de continuer. Cette clé sera utilisée pour tous les appels d'outil suivants relatifs à cette API.

Si l'API demandée ne figure pas dans la liste :

• Informez l'utilisateur que l'API n'est pas actuellement disponible dans ce plugin (context-matic) et arrêtez-vous.
• Demandez à l'utilisateur des conseils sur comment procéder avec l'intégration de l'API.

3. Obtenir des directives d'intégration

• Fournissez à ask : language, key (à partir de l'étape 2), et votre query.
• Divisez les questions complexes en requêtes plus petites et ciblées pour de meilleurs résultats :
  • « Comment s'authentifier ? »
  • « Comment créer un paiement ? »
  • « Quelles sont les limites de débit ? »

4. Consulter les modèles et endpoints du SDK (selon les besoins)

Ces outils retournent uniquement des définitions — ils n'appellent pas les APIs ni ne génèrent de code.

• model_search — consulter une définition de modèle/objet.
  • Fournissez : language, key, et un nom de modèle exact ou partiel sensible à la casse en tant que query (par exemple availableBalance, TransactionId).
• endpoint_search — consulter les détails de la méthode d'un endpoint.
  • Fournissez : language, key, et un nom de méthode exact ou partiel sensible à la casse en tant que query (par exemple createUser, get_account_balance).

5. Enregistrer les jalons

Appelez update_activity (avec le milestone approprié) chaque fois que l'un de ces jalons est concrètement atteint dans le code ou l'infrastructure — pas simplement mentionné ou planifié :

Checklist

• [ ] Langage principal du projet détecté (étape 1a)
• [ ] add_guidelines appelé si les fichiers de directives manquaient, sinon ignoré
• [ ] add_skills appelé si {language}-conventions manquait, sinon ignoré
• [ ] fetch_api appelé avec language et key corrects (nom de l'API)
• [ ] key correcte identifiée pour l'API demandée (ou utilisateur informé si non trouvée)
• [ ] update_activity appelé uniquement quand un jalon est concrètement atteint dans le code/infrastructure — jamais pour les questions, les recherches, ou les consultations d'outils
• [ ] update_activity appelé avec le milestone approprié à chaque jalon d'intégration
• [ ] ask utilisé pour les directives d'intégration et les exemples de code
• [ ] model_search / endpoint_search utilisé selon les besoins pour les détails du SDK
• [ ] Le projet se compile après chaque modification de code

Notes

• API non trouvée : Si une API manque de fetch_api, ne devinez pas l'utilisation du SDK — informez l'utilisateur que l'API n'est pas actuellement disponible dans ce plugin et arrêtez-vous.
• update_activity et fetch_api : fetch_api est la découverte d'API, pas l'intégration — n'appelez pas update_activity avant celui-ci.