🤸🏽 👩🏽‍🤝‍👩🏼 🔶 Guide de style API, ou ne faites pas réfléchir les utilisateurs ✊🏼 🕴🏿 🙏🏿

salut! Je m'appelle Lesha Rutskoi et je suis chef de produit chez Wrike. Auparavant, il a travaillé chez Adform et PandaDoc. Depuis cinq ans, je fais tout ce qui concerne les intégrations et les API.

Wrike est un produit de collaboration et de gestion de projet SaaS. Nous voulons que les développeurs construisent leurs solutions sur la base de Wrike, et pour cela, nous avons besoin que notre API soit pratique. Dans le même temps, nous avons 9 bureaux dans le monde et 3 d'entre eux sont des bureaux de développement. Il est assez difficile de créer une API cohérente à l'aide d'équipes réparties parlant différentes langues. Il est de plus en plus probable que leurs décisions commencent à se contredire. Dans ce cas, on ne peut se passer d'un ensemble uniforme de règles pour tous.

Si vous travaillez également de manière distribuée et créez votre propre API, l'API Style Guide peut vous aider. Je veux vous dire quels problèmes communs il résout et comment cela facilite la vie des développeurs. Je partagerai également mon expérience dans la rédaction et la mise en œuvre de mon propre guide de style API dans l'entreprise.

Pourquoi avons-nous besoin d'une API pratique?

De nombreux lecteurs ont probablement dû résoudre des problèmes en utilisant l'API pas si pratique. Oui, ce n'est pas très simple et prend plus de temps, mais généralement vous pouvez toujours résoudre le problème.

Alors pourquoi perdre du temps et des efforts d'équipe pour améliorer l'API? La réponse est assez simple: très souvent, la décision concernant l'utilisation de votre produit est prise par les développeurs, notamment en ce qui concerne les API et les intégrations. Par conséquent, il est important de penser non seulement à l'expérience utilisateur (UX), mais aussi à l'expérience des développeurs DX.

Je vais vous donner un exemple. Une fois, j'ai travaillé dans une équipe qui était responsable de toute l'intégration des produits. Souvent, au milieu du trimestre, lorsque nos plans étaient déjà définis, un responsable marketing est venu et a déclaré: «Z a créé un nouveau marché et publiera la prochaine version de sa plate-forme. Bientôt, ils auront un événement public sympa où nous pourrons parler de notre intégration et de notre succès! Ce sera formidable si nous écrivons rapidement cette intégration maintenant. » Qu'avons-nous fait dans ce cas? Si un développeur expérimenté dans une équipe pouvait réaliser le prototype de travail minimum en trois jours, le plus souvent en deux ou trois semaines, nous avons réussi à mettre la tâche en parfait état. Si quelques jours manquaient, alors l'API et la documentation étaient telles.Il était inutile pour nous de redessiner des plans et d'entreprendre une nouvelle intégration - tout de même, rien de valable n'aurait fonctionné à la date prévue. N'oubliez pas que votre produit peut être dans cette situation - les partenaires décideront de traiter avec vous en fonction de la rapidité et de la facilité avec laquelle vous pouvez commencer à travailler avec votre API.

Mais presque personne ne veut concevoir une mauvaise API. Pourquoi tout le monde est-il différent? En règle générale, une API se développe comme ceci. Lorsqu'une startup commence à se développer et que les premiers clients y viennent, une des équipes fait son point de terminaison et décide de transférer la version vers l'URL:

progressivement de nouveaux clients et de nouveaux besoins apparaissent. Les gars de la deuxième équipe sont inclus dans le travail, qui pensent qu'il est préférable d'utiliser leurs propres types de médias pour le versioning:

après un certain temps, la troisième équipe arrive. Lors d'une conférence, ils apprennent que Stripe versionne son API avec les dates de sortie principales. Et ils décident de faire de même:

le résultat est une API dans laquelle il existe trois méthodes de versioning. Toutes les méthodes fonctionnent, mais fonctionnent différemment.

En tant que développeur, il serait gênant pour moi d'utiliser une telle API. Et la raison n'est pas que je préfère une approche au versioning à tout le monde. L'utilisation de plusieurs méthodes en même temps n'est pas pratique. Vous devrez écrire trois fois du code qui fonctionne avec l'API ou utiliser trois bibliothèques différentes. Et cela signifie qu'il y aura trois fois plus d'erreurs.

Et il y a des dates et des heures. Même en utilisant l'approche standard, les données peuvent être transmises de différentes manières: par le fuseau horaire de votre serveur, par GMT, par l'heure du client, en temps Unix. Les clients devront rassembler toutes les données dans un seul format.

Les messages d'erreur font généralement tout différemment. Par exemple, comme ceci:

Ou comme ceci:

Il y a aussi mon message d'erreur préféré - une réponse vide:

Eh bien, juste un classique - la réponse est 200 OK, à l'intérieur de laquelle se trouve JSON avec une description de ce qui n'a pas fonctionné.

À mon avis, la chose la plus importante dans une bonne API est la cohérence . Peu importe l'approche de version que vous choisissez, l'essentiel est que ce soit la même dans toute l'API. Une solution encore plus efficace consisterait à adopter l'approche populaire que d'autres sociétés adoptent déjà. Très probablement, vos clients l'ont déjà rencontré et ils ont du code prêt à l'emploi ou une bibliothèque. Plus besoin de réfléchir, vous pouvez utiliser des outils prêts à l'emploi.

Une approche unique pour créer une API est particulièrement importante pour les grandes entreprises avec des équipes réparties. Si dix personnes dans la salle créent une startup, chaque développeur peut simplement frapper un voisin sur l'épaule et accepter ou voir les principaux problèmes lors de la révision du code. Dans une grande entreprise, cela devient plus difficile.

L'API Style Guide vous aidera à résoudre ces problèmes. Il s'agit d'un document qui décrit les principes de conception de votre API. Si tout le monde utilise les mêmes approches, il semble que l'API ait été développée par une seule personne et pas beaucoup d'équipes différentes. Cette approche ressemble beaucoup au Code Style Guide lorsque les équipes s'entendent sur la façon dont elles écrivent le code. Une personne d'une équipe peut consulter la base de code d'une autre équipe et comprendre rapidement ce qui s'y passe.

Comment créer votre propre guide de style API?

Arnauld Lauret (connu comme l' API Handyman ) a créé un site sympa - API Stylebook . Il a élaboré un guide de style accessible au public, que diverses entreprises (Cisco, Google, Red Hat, les agences gouvernementales et bien d'autres) ont mis dans le domaine public.

Les directives sont divisées en sujets sur le site. Par exemple, si vous êtes intéressé par le contrôle de version, dans l'onglet Contrôle de version, vous pouvez découvrir comment différentes entreprises résolvent ce problème.

Apprenez de l'expérience des autres! Mais copier complètement le guide de style de quelqu'un d'autre n'est pas une bonne idée. Pourtant, il résout les problèmes d'une autre entreprise, pas la vôtre.

Dans votre guide de style, vous devez ajouter des sujets proches de votre entreprise et résoudre vos problèmes. Peut-être que vous avez beaucoup d'applications mobiles et que la taille de la réponse est importante pour vous. Décrivez ensuite les principes associés à cet aspect. Ou vous avez convenu avec les équipes internes qu'il était temps de voir le monolithe dans des microservices qui communiqueraient entre eux via Message Broker. Dans ce cas, vous devez inclure les principes selon lesquels vous allez utiliser Kafka ou un autre outil dans le Guide de style API.

Quoi d'autre à inclure dans l'API Style Guide

En outre, le guide de style doit inclure les valeurs de base et les approches d'ingénierie auxquelles l'entreprise adhère.

Que peuvent-ils être?

Write APIs in English. , . - , , . Style Guide, , .
API First principle. API : , , frontend-. , API . , , .
Utilisez REST et JSON. Cela peut être important si vous souhaitez que le public le plus large possible utilise votre API ou votre plate-forme. Malgré le fait que GraphQL soit devenu de plus en plus populaire depuis 2017, tout le monde ne le sait pas. La plupart des développeurs ne l'ont probablement jamais utilisé, ce qui signifie qu'ils augmenteront le temps d'immersion et de développement. Pourquoi créer de la complexité?

De plus, les principes de base peuvent être exposés sur des sujets. Par exemple, à l'intérieur du principe d'utilisation de REST et JSON, vous pouvez facilement déterminer quels sujets doivent être décrits dans le Guide:

Préférez l'API REST avec les charges utiles JSON
- Demandes HTTP
- Codes d'état HTTP
- Json

Plus loin sur chaque sujet, vous pouvez trouver les règles que toutes les équipes de l'entreprise doivent suivre:

Demandes HTTP
- DOIT utiliser correctement les méthodes HTTP
- Les en-têtes HTTP personnalisés DEVRAIENT suivre la convention de dénomination

J'aime vraiment l'approche qui décrit la nécessité de suivre les règles à travers les verbes DOIT, DEVRAIT ou MAI (emprunté à RFC 2119 ). Ensuite, tous ceux qui liront le Guide de style feront la distinction entre les règles obligatoires et les recommandations.

Voici à quoi cela ressemble, par exemple, dans Zalando :

Éléments à garder à l'esprit lors du démarrage du Guide de style

. , . , , . , , . API management , . API.
. - 15- . rate limiting, .. — , , - .
. , OAuth, REST. , , , scopes .
. , , .
. , . , . . . , .
. , , .
. , , .. : , «user», , «user», .
. , — . , (OpenAPI-, -) . .

API Style Guide?

Vous avez créé votre guide de style API et il ne reste plus qu'à l'implémenter. Ce n'est pas facile non plus. Je partagerai mon expérience de la mise en œuvre du Guide de style API dans l'un des endroits où j'ai travaillé. L'entreprise avait une structure complexe: des centaines d'ingénieurs, des dizaines d'équipes réparties dans quatre bureaux de développement, des collègues parlant différentes langues.

Vous devez d'abord convaincre les parties prenantes. Et ici, nous parlons souvent à la fois de leaders techniques dans divers domaines et de représentants d'entreprises. Tout le monde devrait comprendre quels problèmes nous voulons résoudre et comment le Guide de style peut vous aider. Dans mon exemple, toutes les parties prenantes ont compris qu'une bonne API est un avantage important. De nombreux clients sont venus avec une telle demande, et les concurrents ne se sont pas assoupis et ont activement étendu la portée des opportunités disponibles via leur API.

La prochaine étape consiste à trouver une équipe qui le fera. Dans mon cas, l'entreprise disposait déjà d'une équipe distincte prenant en charge une API externe. Elle comprenait le mieux le besoin de changement, car elle était constamment confrontée à des difficultés dans son travail. Les membres de cette équipe ont été ravis de participer au projet.

Comment l'équipe a-t-elle implémenté l'API Style Guide?

Elle a parlé de l'initiative lors de conférences internes et de hackathons afin que tout le monde dans l'entreprise comprenne ce qui était discuté. Cela a aidé à attirer des personnes partageant les mêmes idées qui étaient très utiles dans les étapes suivantes.
A préparé un projet de guide de style, qui a ensuite convenu avec les champions de l'API (à leur sujet un peu plus loin).
Présentation du projet aux équipes. Les gars se sont rendus dans chaque bureau de développement et ont discuté avec presque toutes les équipes, expliqué le sens du projet et organisé des formations.
Aide à la conception de l'API. Il était difficile pour de nombreuses équipes de tout faire sur le guide la première fois. L'aide et des explications supplémentaires ont été utiles ici, en particulier dans des situations inhabituelles.
A effectué un examen. Il était important de vérifier que toutes les équipes agissent conformément au Guide de style.

Il est très difficile pour une équipe d'une grande entreprise de mettre en œuvre des changements aussi importants. Besoin de soutien. Ici, les champions de l'API étaient connectés - des architectes et des diaporamas de chaque direction qui ont contribué à intégrer l'idée dans leurs équipes et divisions.

Lorsque des changements clés ont lieu, un mécontentement apparaît souvent. Dans ce cas, vous avez besoin d'une autorité capable de convaincre ces personnes de la nécessité du changement. Les tehlids sont les personnes les plus appropriées pour cela.

Les champions de l'API dans un canal Slack distinct ont discuté des problèmes émergents et des suggestions. Des changements mineurs ont été introduits immédiatement, tandis que les plus grands nécessitaient une discussion détaillée. Dans ce cas, l'initiateur a écrit une proposition officielle: quel problème doit être résolu, quelles méthodes de solution existent déjà, quels sont leurs avantages et leurs inconvénients. Ensuite, pendant 1 à 2 jours, nous nous sommes réunis hors site à l'extérieur du bureau, avons discuté des idées, choisi une solution et l'avons fixée. Ensuite, nous avons informé nos équipes de la décision que nous avons prise: pourquoi nous l'avons prise et ce qui doit être fait ensuite.

En outre, les champions de l'API ont aidé à effectuer des évaluations dans leurs domaines. Les gars de leurs équipes se sont d'abord tournés vers eux, puis la révision finale a été menée par l'équipe qui créait le Guide de style.

Après un certain temps, une communauté d'API a commencé à se former dans l'entreprise. Il comprenait des personnes qui ont traversé plusieurs cycles d'examen, compris ce qu'est un bon et correct design, pourquoi il est nécessaire et comment le faire. Nous avons créé une grande discussion dans laquelle tout le monde pouvait poser une question, et les membres de la communauté API ont aidé à la résoudre.

Vous ne pouvez pas implémenter l'approche uniquement au niveau de l'ingénierie. Les équipes de vente, de support et de marketing doivent également comprendre quels scénarios utilisateur sont couverts par l'API, quelle valeur elle apporte, comment elle est liée à la stratégie de l'entreprise et comment transmettre correctement les informations à ce sujet aux clients.

Nous avons essayé d'introduire tout cela dans l'intégration de la plupart des équipes de l'entreprise, y compris celles non techniques. Cela est également nécessaire pour que tout le monde comprenne quand, dans quels cas et à qui vous pouvez demander de l'aide.

Automatisation

Le dernier sujet important est l'automatisation des processus de routine. L'examen peut servir d'exemple principal. Dans une grande entreprise avec un grand nombre d'équipes, vous devrez probablement effectuer de nombreuses révisions. Je n'ai pas envie de perdre du temps sur des problèmes de base comme une description d'erreur manquante ou un format d'ID incorrect.

Certains outils peuvent vous y aider:

Zally de Zalando vérifie si la spécification OpenAPI correspond à votre guide de style API. La configuration de base de Zally vérifie la conformité avec le Zalando Style Guide, mais vous pouvez redéfinir et ajouter vos propres règles.
Apiary's Dredd vérifie si l'implémentation finale de l'API REST correspond à votre conception, à savoir les spécifications OpenAPI, Blueprint ou RAML.

Cet article est une transcription de mon entretien avec la conférence Platform Developers de Miro . Vous pouvez trouver la vidéo du discours ici .

Je serai ravi de répondre à vos questions sur la mise en œuvre du Guide de style API. Ce sera également cool si vous partagez une expérience similaire!

Un merci spécial à Daria Ivanova pour son aide dans la préparation de cet article!