À quoi s'attendre
L'objectif est de montrer aux développeurs les problèmes rencontrés par leurs utilisateurs d'API sur l'exemple du travail avec divers systèmes CRM.
Afin de protéger mon visage, je ne publierai pas les noms des participants dans cet article.
De plus, je - je ne suis pas un programmeur de la petite amie de ma mère, alors ne prenez pas mes conclusions pour la seule vraie option.
Eyeliner
Il était une fois un garçon plein d'espoir. Ce garçon n'avait rien dans sa vie à part travailler dans le support technique des programmes de comptabilité. Il a cuisiné dans ce chaudron pendant longtemps, jusqu'à ce qu'un jour, il arrache son toit, et il envoie le trait d'hôte principal et part à la recherche de perspectives.
Le garçon a toujours rêvé de comment il deviendrait un développeur cool, il gagnerait de l'argent extraordinaire, de préférence dans la devise Basurm. Et donc, parallèlement au travail, il s'est engagé dans la création de son site, en utilisant des technologies sans précédent, mais avec des fonctionnalités inouïes pendant ces années. Grâce à cela, il a pu trouver un nouveau propriétaire, qui lui a donné un emploi dans son entreprise préférée, avec un bon salaire et des perspectives irréalistes.
Depuis lors, le garçon a vécu, vécu et guéri. Et il ne connaissait pas les ennuis et les peines ... ou le savait-il? Voyons ça!
J'ai obtenu un emploi dans une entreprise de veille économique. Et quel type d'analyse peut être sans données? Par conséquent, la société avait une équipe distincte, puis un département qui était engagé dans la collecte de données sur les sites clients pour établir des calendriers de revenus à partir des canaux publicitaires et d'autres sources. En ce qui concerne les détails, mon travail consistait à installer notre compteur sur les sites, à collecter des données sur le visiteur et à créer des applications à partir de formulaires, de chats en ligne, de rappels, etc. dans leurs systèmes CRM. Dont, à l'avenir, nos analyses ont recueilli des informations sur l'état et le montant de la vente.
Et il ne semble y avoir rien de compliqué ici, étant donné que la création d'applications dans CRM a été simplifiée en enveloppant notre système, qui, à l'aide d'une seule demande, a créé l'application et le client, y compris la prise en charge de services tiers. Mais comme vous devez le comprendre, une telle logique ne diffère pas par sa flexibilité. Et si le client avait besoin de quelque chose de non standard, il était déjà nécessaire de «désactiver le mode confort» et de retrousser ses manches pour travailler directement avec l'API du système souhaité. Et parfois, en travaillant avec la prochaine API problématique,
je pense qu'il vaut mieux y rester. soutien ...
Problème n ° 1: manque de méthodes / données
Le problème le plus courant que j'ai rencontré au cours de ma vie est peut-être le manque de capacité à obtenir les données dont j'ai besoin dans l'interface. Des conflits avec les clients ont constamment surgi et continuent de survenir, car nous ne pouvons pas voir quotidiennement quelque chose qu'ils voient sur les écrans de leurs moniteurs.
Par exemple, il y a quelques années, un client assez important est venu chez nous qui avait besoin de sauvegarder dans des fichiers CRM que les clients lui envoient à partir des formulaires sur le site. Une tâche ordinaire, mais il n'y avait aucune possibilité de mise en œuvre, et non à ce jour!
L'échec pour le client était inacceptable, et à la fin nous avons dû télécharger des fichiers, émulant des requêtes JS à partir de l'interface.
Je dois dire que ce CRM, autorisation dans l'API, autorise également dans l'interface, ce qui, pour moi, est une solution assez étrange. Cependant, grâce à cela, nous n'avons pas eu à émuler l'autorisation habituelle. Ou, a-t-il été conçu ...?Un autre cas avec le même CRM s'est produit il n'y a pas si longtemps. Il fallait tenir responsable du gestionnaire d'application qui est actuellement actif. Et comme vous l'avez déjà compris, l'API ne nous renvoie pas d'informations sur l'activité du responsable. Mais le paradoxe est que leur API JS revient. En conséquence, j'ai dû écrire une application JS, une sorte d'intermédiaire, avec laquelle j'ai informé le serveur des gestionnaires actifs en ce moment.
Solution:Dans notre équipe, il est de coutume de créer une méthode d'API publique pour l'interface et d'interagir avec le serveur à travers elle déjà. Cela élimine le problème de non-concordance entre les capacités techniques de l'interface et l'API publique.
Problème numéro 2: l'absence d'un style uniforme de demandes / réponses
Un problème très courant même dans les grands CRM occidentaux. Supposons que nous ayons besoin d'obtenir une liste de commandes pour un mois, nous découvrons que le système a une limite sur le nombre d'éléments dans le téléchargement. Et pour parcourir les pages, vous devez utiliser le paramètre offset. D'accord, nous avons implémenté la méthode de chargement des commandes, et séparément, la méthode auxiliaire de pagination.
Maintenant, nous devons décharger la liste des clients, nous implémentons une nouvelle méthode avec la méthode de pagination écrite plus tôt, et ... nous obtenons une erreur. Parce que PM et les développeurs ont décidé que les sons d'offset étaient trop faciles, laissez-le maintenant être vid-offset.
Bien sûr, j'exagère, je ne peux pas savoir ce qui s'est passé quand ils ont écrit cette API. Mais c'est au moins une erreur PM, car il n'a pas précisé comment cela était déjà implémenté dans d'autres méthodes. Et aussi une erreur des développeurs, de ceux qui ont écrit une nouvelle méthode et de ceux qui ont été vérifiés. Pour l'instant, tous ceux qui utilisent leur API sont obligés de construire des béquilles dans leurs applications.
Solution:Toute nouvelle méthode api, si possible, doit correspondre à la structure des méthodes existantes. Le responsable technique (ou chef d'équipe faute du premier) peut élaborer un règlement, une sorte de style de code, selon lequel il est nécessaire de développer une API, et sans faute de la familiariser avec tous les développeurs. Si le problème a déjà sa place, alors, si possible, il vaut mieux mettre une béquille de votre côté que de forcer des milliers de vos clients à le faire de votre côté.
Problème numéro 3: mauvaise documentation ou absence de documentation
La documentation est une référence pour les développeurs. Nous rencontrons souvent des situations où nous sommes interrogés sur la possibilité de mettre en œuvre une fonctionnalité particulière. Et si nous ne nous souvenons pas ou ne connaissons pas la réponse, ouvrez immédiatement la documentation. Trouver des informations dans un bon répertoire est un travail de quelques minutes, tandis que dans un répertoire surchargé, vous pouvez creuser pendant une demi-heure, et vous n'obtiendrez toujours pas de réponse définitive.
Dans certains cas avancés, il est tout simplement impossible de trouver dans le domaine public. Et si vous souhaitez obtenir une liste à jour des méthodes, vous devez contacter le support technique. Et puis vous devez encore vérifier si quelque chose de nouveau est apparu là-bas, que nous avons demandé à quelques clients ...
Solution:Je vais donner quelques points qui, quant à moi, caractérisent une documentation de qualité:
- recherche par nom, description et paramètres de méthode
- description correcte de l'objectif de la méthode
- liste des paramètres acceptés avec type et description
- liste des paramètres retournés avec type et description
- exemple de demande
- exemple de réponse
- codes d'erreur possibles avec une description
- un bac à sable dans lequel vous pouvez "jouer" avec les demandes en mode conception
- modifier l'historique de toutes les méthodes api pour une référence rapide
Problème numéro 4: les vélos d'autorisation
Vous savez ce merveilleux sentiment lorsque vous ouvrez la documentation d'un nouveau système, et là, dans la section autorisation, un ordre de 3 méthodes est décrit pour obtenir une clé valable pour 1 seule demande ...? Donc, je ne l'ai pas.
Cela reste un mystère pour moi pourquoi les développeurs abandonnent Oauth 2.0 au profit de leurs vélos? Et bien, si l'autorisation est limitée à un jeton constant, mais voici toute la chaîne d'autorisation ...
Solution:Vous ne devez pas réinventer votre vélo alors qu'il existe déjà des normes toutes faites. En effet, pour ces standards, les développeurs ont déjà leurs propres composants pour une simple autorisation.
Épilogue
J'ai parlé de 4 problèmes que j'ai rencontrés au début de mon voyage jusqu'à ce jour. J'ai essayé de fournir leurs solutions, mais c'est à vous de décider si elles sont bonnes ou non. En fin de compte, chacun de nous a sa propre architecture de pensée.
Je remercie donc tous ceux qui ont lu jusqu'à présent! Ceci est mon premier article, et s'il avait une valeur informative pour vous, alors je serais heureux de continuer la série d'articles sur ma souffrance avec l'API.
Et bien sûr, je serai heureux d'entendre les opinions des experts dans les commentaires.
Le tout avec le 2020 à venir!