Pendant un an et demi, nous avons intégré l'API à vingt services externes. Les cinq premières intégrations ont traversé des douleurs et des larmes - nous avons fait toutes les erreurs possibles. Ils ont réécrit le code plusieurs fois, se sont séparés avec des partenaires juste avant la sortie, car ils ne pouvaient pas s'entendre sur les améliorations. Perdu temps et argent.
Mais à chaque nouvelle intégration, nous avons trouvé des solutions aux problèmes récurrents. En conséquence, nous avons effectué la dernière intégration quatre fois plus rapidement que la première. Ce que nous faisons maintenant différemment - lire l'article.
Afin de mieux comprendre les spécificités de nos intégrations, nous décrirons brièvement ce que nous faisons. Nous développons un courtier en ligne. Principe de travail: l'internaute se rend sur le site, remplit le questionnaire, nous le transmettons à des organisations de microfinance (IMF) et recevons de leur part un agrément ou un refus de prêt. L'utilisateur sélectionne une offre appropriée et reçoit de l'argent. Pour que cela fonctionne en ligne, nous nous intégrons aux IMF via l'API.
Évaluer la préparation des partenaires à l'intégration à l'aide d'une liste de contrôle et de spécifications
Nous analyserons deux scénarios: lorsqu'un partenaire potentiel dispose déjà d'une API pour accepter des candidatures, et quand ce n'est pas le cas. Les deux scénarios suggèrent que le partenaire souhaite s'intégrer avec nous et est prêt à y consacrer du temps.
Le partenaire n'a pas d'API - nous envoyons la spécification
Auparavant, nous avons expliqué au partenaire, verbalement ou par correspondance, ce dont nous avions besoin pour l'intégration, et le partenaire, sur la base de ces explications, a créé une API pour accepter les applications avec Finspin. Nous ne nous sommes pas mis d'accord sur les exigences pour les modèles, les objets, les champs du questionnaire et les règles de leur validation. Décrit rapidement l'objectif des méthodes et les réponses possibles. Le résultat s'est avéré être infiniment loin de ce qui était attendu, car notre compréhension de l'API était très différente de celle du partenariat. J'ai dû tout refaire.
Maintenant . Nous avons écrit notre spécification - un fichier YAML qui peut être ouvert dans Swagger. Dans la spécification, nous avons décrit l'API la plus appropriée pour intégrer Finspin aux IMF: champs de questionnaire et règles pour leur validation, formats et types de demandes avec réponses, noms de méthode, erreurs et statuts possibles. Nous avons enregistré l'état de la demande que nous prévoyons de recevoir, par exemple: «accepté pour traitement», «notation en cours», «prêt refusé», «approbation», etc.
Nous envoyons la spécification au partenaire, et il décide s'il peut fournir une telle API. Si ce n'est pas le cas, note des points problématiques dans la spécification, par exemple, tous les états de l'application ne sont pas prêts à être transférés vers l'API ou il n'y a pas suffisamment de champs dans le questionnaire. Et nous discutons déjà de points spécifiques, pas d'entités abstraites. Le partenaire ne perd pas de temps à rédiger sa documentation, mais ajuste la nôtre.
Nous avons passé deux jours à créer la spécification, mais nous économisons maintenant des dizaines d'heures sur les approbations et les améliorations de l'API. De plus, à l'aide des spécifications, nous filtrons rapidement les partenaires qui ne sont pas prêts pour l'intégration. Au tout début, il devient clair que nos processus de traitement des demandes en ligne sont très différents: il n'est pas rentable de les intégrer.
Le partenaire dispose d'une API - parcourez la liste de contrôle
Nous avions l'
habitude d'obtenir les spécifications d'un partenaire et de poser des questions en déplacement. Souvent, ils ont oublié de clarifier quelque chose d'important, puis cet important est apparu aux étapes finales du développement et des tests, quand il est devenu particulièrement coûteux de corriger et de réécrire. D'une manière ou d'une autre, à la fin de l'intégration avec un partenaire, il s'est avéré qu'il transfèrerait le statut des prêts via l'API avec un retard de plusieurs jours. Pour nous, c'est inacceptable. Le partenariat a dû être abandonné.
Maintenant . Nous avons rédigé une liste de contrôle pour évaluer l'API et les processus qu'elle sert. La liste de contrôle rassemblait des questions auxquelles il fallait répondre. Tout d'abord, notre responsable recherche des réponses dans le cahier des charges. S'il n'est pas trouvé, adresse des questions au partenaire.
La liste de contrôle vous aide à trouver les goulots d'étranglement avant de commencer le développement, et non après - lorsque vous devez modifier le code et que les clients souffrent d'un mauvais service.
Nous remplissons constamment la liste de contrôle lorsque nous sommes confrontés à de nouvelles situations. Plus la liste de contrôle est détaillée, plus le risque d'erreurs de développement est faible.
Fragment de liste de contrôle APIGlossaire des termes
Auparavant, il nous semblait que dans le domaine du prêt en ligne, tout le monde comprend les termes professionnels de la même manière, il ne peut y avoir de divergence. La pratique a montré que nous avions tort.
Par exemple, avec une IMF, nous avons interprété différemment les clients principaux et les clients récurrents. Pour nous, le client principal est le client dont le profil est entré pour la première fois dans la base de données MFI via Finspin, et le client récurrent était déjà dans la base de données. Le partenaire considérait les clients fidèles par le nombre de prêts accordés: les répétitions ont reçu deux prêts et sont venus pour un troisième. Une telle confusion terminologique pourrait entraîner des incohérences dans les rapprochements financiers.
Nous utilisons
maintenant un petit glossaire de termes par lequel nous vérifions avec nos partenaires. En règle générale, il suffit de clarifier cinq ou six termes de base afin de synchroniser les idées d'intégration et d'évaluer les perspectives de collaboration.
Une fois qu'un glossaire nous a permis d'éviter une intégration désavantageuse. Notre interprétation de «l'approbation» était très différente de celle de l'affilié. L’approbation du partenaire comprenait de nombreux aspects différents qui nécessitaient un traitement manuel. Nous visons une automatisation maximale, nous avons donc immédiatement refusé de coopérer.
Clarifier le terme «approbation»Première entreprise, puis développement
Il y avait des cas où nous avons commencé à travailler avec un partenaire potentiel avec une spécification. Notre responsable a reçu les spécifications, les a étudiées attentivement, a précisé les détails de l'intégration avec le partenaire, discuté des problèmes litigieux avec les développeurs. Et puis un message est venu des dirigeants: "Fin, l'intégration est annulée, nous ne nous sommes pas mis d'accord sur les conditions". Les employés ont perdu du temps.
Lorsque vous changez d'avis et que le travail est terminéMaintenant, la règle de fer
est en vigueur: le gestionnaire commence à étudier le cahier des charges uniquement lorsqu'il reçoit une décision claire de l'intégration de la part de la direction.
Préparation à l'intégration: URL, détails, environnement
Auparavant, le premier appel à l'API partenaire s'est produit lors des tests de notre application, à partir des serveurs de développement. Souvent, les premières demandes ont reçu des erreurs lors de la configuration de la connexion: impossible de se connecter au serveur ou simplement un délai d'attente. Raisons les plus populaires:
- Noms de méthode incorrects (scellés ou confus)
- Domaine invalide
- détails de connexion erronés,
- Nous n'avons pas ajouté l'IP de nos serveurs à la liste blanche.
Il a fallu des heures pour corriger ces erreurs mineures, car elles se sont succédé: jusqu'à ce que vous en corrigiez une, vous ne verrez pas la suivante.
Maintenant , avant d'intégrer la tâche dans le plan de développement, nous clarifions toutes les fonctionnalités d'accès à l'API avec une petite liste de contrôle. La liste de contrôle répertorie les points à clarifier, par exemple:
- restrictions sur la charge du service,
- le nombre de demandes par unité de temps
- détails de connexion
- liste blanche par adresses IP,
- Validation du certificat SSL
- exigences de chiffrement du trafic,
- en-têtes spéciaux dans les demandes
- la présence d'un serveur de test avec API ou la possibilité d'envoyer des requêtes de test au serveur de combat
S'il existe une API de test, nous découvrirons certainement quelle est la différence lors de l'accès au serveur de combat et au serveur de test. Nous prenons en compte les différences lors de la création de demandes depuis notre application vers des partenaires dans des environnements de développement et de production. Ces mesures nous aident à comprendre si les systèmes sont prêts pour nos besoins ou si des ajustements supplémentaires sont nécessaires.
Envoi manuel de demandes à l'API
Avant, nous écrivions immédiatement le code selon les spécifications du partenaire, rédigions les spécifications, révisions, testions. Et au stade des tests d'intégration, il s'est avéré que tout ce qui est écrit dans le cahier des charges ne correspond pas à la réalité - à partir du format des requêtes, pour finir avec le processus de réussite de l'application.
Par exemple, selon la spécification, lorsque nous accédons à une certaine méthode, nous attendons une réponse dans un certain format dans la réponse, suspendons le traitement pour la validité de la réponse reçue, passons aux tests et tout à coup, nous obtenons un tableau dans la réponse. Nous découvrons les raisons auprès des développeurs du partenaire. Ils font référence à une documentation obsolète. Encore une fois, un cercle d'améliorations, d'examens et de tests.
Désormais , dès que nous recevons la documentation et les détails de connexion, nous exécutons le processus via le client API. En règle générale, le testeur télécharge la spécification sur Postman et simule le processus commercial complet d'envoi d'une demande de prêt, vérifie les cas les plus courants avec différents ensembles de données pour la demande. Autrement dit, fait manuellement ce que l'application fera ensuite.
Au stade d'une exécution manuelle, 80% des inexactitudes dans la documentation sont révélées. Nous décrivons les erreurs et les transmettons au partenaire. Le partenaire élimine les inexactitudes à la maison ou finalise la spécification. Par conséquent, au moment où le travail sur le code commence, les développeurs reçoivent une documentation de travail.
Écarts les plus courants:
- format de demande incorrect, promesse d'accepter json, il s'est avéré avoir besoin de données de formulaire;
- Erreurs dans les noms des champs à transmettre dans la demande;
- erreurs dans les formats de champ;
- les règles de validation des champs ne sont pas spécifiées ou sont indiquées de manière incorrecte;
- certains domaines peuvent être complètement oubliés;
- manquant ou différent de la description réelle du format de réponse de la méthode;
- marques erronées sur les champs obligatoires - des «astérisques» peuvent apparaître là où le champ n'est pas obligatoire en fait, et vice versa;
- souvent pas documenté tous les états et statuts dans lesquels l'objet peut être;
- des écarts entre les états attendu et reçu des objets. Par exemple, à un moment donné, nous nous attendons à ce que l'application soit dans l'état X - et par l'API, en fait, nous obtenons Y.
Recette du bonheur: éviter les erreurs d'intégration d'API
Écrivez une spécification pour l'intégration avec votre service. Nous avons passé deux jours à développer la spécification en YAML, mais nous économisons maintenant des dizaines d'heures sur les améliorations et les approbations.
Si le partenaire envoie sa spécification, vérifiez-la sur la liste de contrôle. Dans la liste de contrôle, recueillez les questions auxquelles vous devez répondre. Ne comptez pas sur l'expérience et la mémoire, manquez toujours quelque chose.
Ayez un glossaire pour éviter toute confusion avec votre partenaire. Notre expérience a montré que les différences peuvent même être en termes évidents.
Ne prenez pas la tâche en développement avant d'avoir reçu l'approbation de principe de la direction de l'intégration avec un partenaire. L'idée est évidente, mais elle nous aide à éviter les travaux inutiles.
Ouvrez une liste de contrôle pour clarifier les détails de l'accès à l'API du partenaire: détails de connexion, liste blanche, validation du certificat SSL, exigences de chiffrement du trafic, etc. Consultez la liste de contrôle dès que possible pour éviter tout glissement aux étapes finales.
Vous avez une spécification - ne vous précipitez pas pour écrire du code immédiatement. Tout d'abord, exécutez manuellement le processus via un client API, par exemple, via Postman. Vous trouverez donc des erreurs dans la spécification à un stade précoce et avec de petites ressources. Et ils le seront.