Commencer par le contrat d’interface de la version à déployer
Obtenez la documentation API pour votre déploiement et vérifiez l’adresse du service, la méthode d’authentification, les structures de demande et de réponse et les fonctionnalités disponibles. OpenAPI est une norme permettant de décrire les opérations, les paramètres et les modèles de données HTTP API. Utilisez le contrat fourni avec le produit pour l’intégration proprement dite.
Ce guide de préparation omet les points de terminaison AI-Soda Brain non vérifiés, les champs d’authentification et les noms de packages SDK. Avant d’écrire du code, demandez au client et aux équipes de service de se mettre d’accord sur le même contrat et la version qu’il couvre.
Liste de contrôle minimale du contrat API
| Article du contrat | Des questions à régler |
|---|---|
| Identité et autorisations | L’opération s’exécute-t-elle en tant qu’utilisateur ou application ? Comment sa portée est-elle limitée ? |
| Demande | Types de champs, champs obligatoires, limites de taille et contraintes d’encodage |
| Réponse | Comment les résultats, les sources, l’état et l’achèvement sont-ils représentés ? |
| Calendrier et annulation | Comment les délais d’attente, les annulations et les états de tâches de longue durée sont-ils gérés ? |
| Échec | Quelles erreurs peuvent être réessayées ? Lesquels nécessitent des entrées ou des autorisations différentes ? |
| Version | Politique de compatibilité, notifications de modification et calendrier de dépréciation |
Effectuez un petit test de bout en bout
- Configurez une identité de moindre privilège dans un environnement de test isolé. Conservez les informations d’identification hors du code frontal et des exemples de référentiels.
- Passez un appel réussi avec une question synthétique et conservez une demande et une réponse rédigées.
- Couvre les entrées invalides, les autorisations insuffisantes, les délais d’attente et l’annulation. Vérifiez que le client affiche un état d’échec distinct plutôt qu’un résultat vide.
- Testez le comportement des champs manquants et inconnus par rapport au contrat avant de connecter l’interface métier.
Nouvelles tentatives de conception autour de l’effet d’une opération
Après une coupure réseau, le serveur peut avoir déjà exécuté l’opération. Avant de relancer une action susceptible d’avoir des effets externes, vérifiez son idempotence et la façon de consulter l’état de la tâche. Pour les requêtes en lecture seule, fixez des limites, des délais croissants entre tentatives et des conditions d’annulation.
Lors de l’acceptation, enregistrez la version du contrat, la version client, les cas de test et les limites connues. Pour les mises à niveau ultérieures, validez les mêmes cas avant d’augmenter progressivement le trafic.
