Se libérer du mode solo : apprendre à collaborer sur le développement d'API avec Postman

Le développement d'API est une grande partie de ce que j'aime dans les logiciels. Qu'il s'agisse de créer des intégrations ou de créer des API pour des applications Web découplées, il s'agit généralement de moi et du code .

La plupart du temps, je travaille en tant que développeur d'API solo. Partir seul a ses avantages : des décisions rapides et un contrôle total. Mais c'est une arme à double tranchant puisque garder tout dans ma tête rend les transferts et la délégation délicats. Et travailler seul limite la taille et la complexité des projets sur lesquels je peux travailler. Après tout, je ne suis qu'une seule personne.

Postman est mon principal outil pour le travail des API : envoyer des requêtes, gérer des environnements et exécuter des tests. Je connais mon flux de travail en solo. Mais j'ai commencé à me demander : dans un environnement d'équipe, que peut offrir de plus Postman ? Comment pourrait-il améliorer la collaboration et rationaliser le processus de développement ?

Pour explorer ces questions, j'ai commencé à travailler sur un exemple d'API, que j'appelle « X Nihilo ».

Exemple d'API : X Nihilo

X Nihilo vous aide à générer des tweets de 280 caractères en fonction des paramètres que vous stockez ou envoyez. Vous fournissez un sujet, un objectif, une description du ton à adopter et une description du public. En coulisses, l'API enverra une demande à l'API d'OpenAI pour la complétion du texte, ce qui aidera à générer le tweet.

De plus, vous pouvez enregistrer les chaînes que vous utilisez pour le ton et l'audience, puis les réutiliser dans les demandes de tweet ultérieures.

Passons en revue mon flux de travail de base de développement d'API.

Faire cavalier seul : mon flux de travail en solo

La première étape de mon flux de travail consiste à concevoir l'API et à rédiger une spécification OpenAPI. Dans Postman, j'ai créé une nouvelle API, puis j'ai commencé une nouvelle définition d'API.

Après réflexion (et travail directement avec ChatGPT, ce qui était idéal pour générer une spécification OpenAPI initiale basée sur mes descriptions), j'ai fait rédiger ma spécification :

Avec ma spécification OpenAPI en place, je suis arrivé à un carrefour sur la route. Dois-je configurer un serveur fictif et quelques exemples de requêtes et de réponses pour montrer à quoi cela ressemblerait d'interagir avec cette API ? Ou devrais-je commencer à écrire du code d’implémentation ?

En tant que développeur solo, je ne peux être qu'un producteur ou un consommateur d'API à un moment donné. J'ai donc décidé : pas besoin de créer des simulations, le consommateur en moi devrait attendre. Écrivons du code !

Quelques instants plus tard…

En utilisant Node.js avec Express et en parlant à une base de données PostgreSQL, j'ai implémenté mon API de base. Voici un aperçu de tout ce dont j'avais besoin pour construire :

• POST /signin prend un username et password , s'authentifie par rapport aux enregistrements de la base de données, puis renvoie un JWT signé, qui peut être utilisé dans toutes les requêtes ultérieures.
• POST /generateTweet génère un tweet de 280 caractères (max). Il faut un topic (chaîne) et un goal (chaîne). Il prend également soit une tone (chaîne) soit un toneId (ID entier d'une tonalité stockée), ainsi qu'une audience (chaîne) ou un audienceId (ID entier d'une audience stockée). Chaque fois que des chaînes tone et/ou audience sont fournies, l'API les enregistre dans la base de données.
• GET /tones renvoie une liste d'ID de tonalité et de chaînes correspondantes. GET /audiences fait de même pour les chaînes d'audience réutilisables.
• DELETE /tones prend un identifiant de tonalité et supprime cet enregistrement de tonalité. DELETE /audiences fait la même chose pour les enregistrements d'audience.

Une fois la mise en œuvre initiale terminée, il était temps de revenir à Postman pour commencer à exécuter certaines requêtes.

Créez un environnement avec des variables.

Tout d’abord, j’ai créé un nouvel environnement appelé « Test ». J'ai ajouté des variables pour stocker mon root_url ainsi qu'un username et password valides.

Créer une collection et une demande

Ensuite, j'ai créé une nouvelle collection et ajouté ma première requête : une requête POST à /signin , pour tester l'authentification.

Avec mon serveur API exécuté dans une fenêtre de terminal, j'ai envoyé ma première requête.

Succès! J'ai reçu mon jeton, dont j'aurais besoin pour toute demande future.

J'ai créé une nouvelle requête, cette fois pour générer un tweet.

Je me suis assuré de définir l' autorisation pour utiliser le « jeton du porteur » et j'ai fourni le jeton que je viens de recevoir lors de la demande précédente.

Voici la réponse :

Ça marche!

Résumer l'approche solo

C'est un aperçu de base de mon flux de travail en solo. Bien sûr, je ferais quelques autres choses en cours de route :

• Écrivez un script de pré-demande pour effectuer une requête /signin , puis définissez une variable d'environnement basée sur le jeton dans la réponse.
• Créez des requêtes pour tous les autres points de terminaison dans la spécification OpenAPI.
• Écrivez des tests pour chaque point de terminaison, en vous assurant de couvrir mes cas extrêmes.

Si je travaille en solo, ce flux de travail de base me rapproche de la ligne d'arrivée. Même si c'est bien, je sais que je ne fais probablement qu'effleurer la surface des fonctionnalités disponibles dans Postman. Et je sais que j’aurais besoin de beaucoup plus de Postman si je travaillais en équipe.

Le moment aha : pourquoi envisager Postman pour les équipes ?

Et si je ne pouvais plus être un développeur d'API solo pour X Nihilo ? Cela peut se produire pour plusieurs raisons :

• X Nihilo grandit en taille et en complexité, et un seul développeur d'API ne suffit plus pour le prendre en charge.
• X Nihilo n'est qu'une petite partie d'un projet API plus vaste impliquant plusieurs développeurs d'API ou peut-être même plusieurs équipes API.

Tous mes projets API pour les clients ne seront pas de petits projets que je pourrai construire moi-même. Parfois, je devrai faire partie d'une équipe qui crée une API. Je devrai peut-être même diriger l'équipe API.

Lorsque cela se produira, je devrai abandonner ma mentalité solo et abandonner ma façon solo de faire les choses dans Postman. Cela m'a motivé à examiner les fonctionnalités liées à l'équipe de Postman.

Explorer les fonctionnalités de l'équipe (entreprise) de Postman

Postman propose un niveau gratuit et offre des fonctionnalités de collaboration limitées, ce qui peut être suffisant si vous êtes une petite équipe (c'est-à-dire pas plus de trois développeurs). Postman dispose de fonctionnalités supplémentaires dans le cadre de son niveau Enterprise Essentials. Ceux-ci sont parfaits pour les équipes API des grandes organisations qui utilisent Postman à tous les niveaux.

Partage d'espace de travail

Un espace de travail permet à vos équipes de collaborer sur plusieurs projets API. C'est très bien si vous avez différentes équipes travaillant sur différentes API, mais que ces API interagissent les unes avec les autres (ce qui est généralement le cas dans les grandes organisations logicielles).

Les espaces de travail sont excellents pour permettre une collaboration en temps réel. Les membres de l'équipe peuvent modifier la documentation de l'API, travailler ensemble à l'élaboration de requêtes ou à l'écriture de tests, et créer un serveur fictif que toute l'équipe peut utiliser. Au fur et à mesure que les modifications sont apportées, elles sont synchronisées avec toute l'équipe en temps réel.

Contrôle de version

Même si je me souciais du contrôle de version de mon code, en tant que développeur d'API solo, je ne me souciais pas beaucoup du contrôle de version de mes collections ou environnements Postman. Si je change quelque chose (modifier une requête, mettre à jour un test, supprimer une variable d'environnement), je suis le seul concerné. Ce n'est pas grave.

Lorsque vous travaillez en équipe, vous voulez absolument savoir quand les choses changent. Et parfois, vous devez annuler les modifications. Heureusement, pour les équipes utilisant Postman Enterprise, Postman vous donne accès à un journal des modifications pour les collections, les espaces de travail et les API. Vous pouvez restaurer les collections à des moments antérieurs. En tant que développeur d'API au sein d'une équipe, vous en aurez besoin. La plupart du temps, c'est parce que Bob a foiré la collection. Mais parfois, tu es Bob.

Accès basé sur les rôles et organisation des utilisateurs

Tout le monde dans un espace de travail Postman ne devrait pas disposer du même niveau d’autorisations. Certains membres de l'équipe sont des testeurs et ils ont simplement besoin de pouvoir envoyer des requêtes et exécuter des tests, mais pas de les modifier. D'autres peuvent être des concepteurs autorisés uniquement à modifier les définitions d'API.

Dans Postman, vous pouvez attribuer des rôles aux membres de l'équipe. Cela affecte le type d'accès et le niveau d'autorisation dont dispose chaque membre de l'équipe au sein d'une équipe ou d'un espace de travail.

Les équipes peuvent également disposer d’espaces de travail privés, limitant ainsi l’accès des personnes extérieures à l’équipe.

J'ai également remarqué que Postman Enterprise prend en charge la « capture de domaine ». Cela signifie essentiellement que vous pouvez configurer tous les utilisateurs de votre organisation en donnant accès à tout le monde à partir du domaine (par exemple) mycompany.biz .

Commentaires et discussions en ligne

Postman dispose d'une fonctionnalité de collaboration, disponible sur tous ses forfaits, pas seulement sur Enterprise Essentials. Il s'agit de la possibilité pour les membres de l'équipe d'ajouter des commentaires aux collections (sur des dossiers, des requêtes, des exemples ou des pull request). Pouvoir commenter et discuter directement dans Postman est énorme pour le développement d'API en équipe. Étant donné que la plupart du travail de développement d'API de votre équipe se déroulera dans Postman, il est logique d'avoir votre discussion là-bas (plutôt que dans GitHub ou un autre service externe).

Développement d'API d'équipe : Postman pour la victoire

Chaque fois que je rejoins une équipe, j'apporte les outils que j'aime utiliser, mais je ne les impose pas vraiment à mes coéquipiers. Je pense qu'ils ont leurs propres outils. Donc à chacun son truc. Mais j'ai le sentiment que la plupart des développeurs d'API ont Postman dans leur ceinture d'outils. Il serait tout simplement dommage que plusieurs développeurs d'API d'une équipe utilisent tous Postman individuellement, dans un état d'esprit solo, et sans profiter de certaines de ces fonctionnalités d'équipe. S’ils profitaient des fonctionnalités de Postman Enterprise, ils obtiendraient…

Efficacité accrue

Dans un espace de travail partagé, vous commencez par la définition de l'API partagée. Chaque fois qu'un membre de l'équipe modifie la définition (ou la documentation, les tests ou les environnements), les modifications sont synchronisées et tout le monde dispose des dernières et meilleures versions.

Tout le monde travaille sur le même ensemble de requêtes dans une collection et tout le monde a accès à tous les tests qui seront utilisés. Toutes ces commodités amélioreront l’efficacité d’une équipe, ce qui à son tour fera monter en flèche leur vitesse de développement.

Moins de malentendus

Lorsque tout le monde travaille à partir de la même source de vérité (votre espace de travail) et qu'ils peuvent faire des commentaires et converser au sein de l'outil qu'ils utilisent pour le développement, cela entraînera moins de malentendus. Votre équipe ne perdra pas de temps à se demander si ce point de terminaison était censé prendre des paramètres de requête ou des paramètres de chemin. Tout sera clair.

À retenir

Je ne savais pas que Postman était destiné aux équipes et aux entreprises. Maintenant que je sais, voici ce que je retiens le plus : les joueurs d’équipe utilisent des outils qui sont bons pour l’équipe.

Postman a été formidable pour moi lorsque je suis développeur d'API solo. Heureusement, il possède également des fonctionnalités qui le rendraient idéal pour moi lorsque je fais partie d'une équipe de développement d'API. Pour moi, il s'agit d'une synchronisation en temps réel des modifications au sein des collections, des journaux de modifications et du contrôle de version, ainsi que d'autorisations d'accès granulaires. Désormais, je suis ravi de me lancer dans des projets API plus importants avec des équipes plus grandes.

Bon codage !

Également publié ici .