Utilisation d'un prototype comme spécification de produit d'API

En tant que responsable produit de l'expérience développeur chez SendGrid, je suis chargé d'identifier les opportunités, les fonctionnalités et les produits qui impliquent notre API. Une chose sur laquelle j'ai travaillé est d'identifier des méthodes pour rendre plus efficace la communication de mes idées de produits aux autres chefs de projet, ingénieurs et clients.

J'ai appris qu'un document d'exigences de produit (PRD) monolithique n'est pas un moyen idéal de le faire et qu'une interface testable comprenant les mêmes informations qu'une spécification de produit serait une alternative puissante. Le problème avec les PRD est qu'ils sont souvent très volumineux et principalement composés de texte. Il est trop facile de perdre sa place ou de manquer quelque chose de vraiment important.

Nos amis de l'UX ont résolu ce problème avec des outils comme Invision , où ils fournissent une interface cliquable que vous pouvez toucher et utiliser, plutôt qu'un document ou un wireframe qui décrit simplement l'interface. Puisqu'une API est une interface, nous avons besoin d'un outil qui permettra une interaction avec la spécification en temps réel, plutôt qu'un tas de texte descriptif et JSON dans un document.

Définir les exigences

À quoi devrait ressembler cette interface testable en tant que spécification de produit ? Comment cela fonctionnerait-il ? Existe-t-il ?

Alors que je lisais le chapitre 18, "Réinventer la spécification de produit", de Marty Cagan's Inspired: How to Build Products Customers Love , j'ai réalisé que je voulais partager un outil que j'utilisais et qui satisfaisait aux exigences de Cagan pour une spécification de produit, la plupart des sa liste de souhaits pour les spécifications du produit et ma propre liste personnelle d'exigences de prototype en tant que spécification.

Exigences de Cagan* :

• La spécification doit décrire l'expérience utilisateur complète.
• La spécification doit représenter avec précision le comportement du logiciel.
• Vous devez être en mesure de communiquer le produit de manière à ce que toutes les parties prenantes obtiennent ce dont elles ont besoin.
• La spécification va changer
• Il doit y avoir une seule représentation principale de la spécification pour réduire l'ambiguïté et la versionite.

La liste de souhaits de Cagan* :

• Vous devrez compléter le prototype [avec] :
  • Logique métier
  • Conditions de publication
  • Exigences de livraison de la plate-forme
  • Cas d'utilisation
• Je veux vraiment pouvoir annoter le prototype

Mes exigences pour le prototype en tant que spécification :

• Le prototype devrait être la spécification.
• La documentation doit être intégrée au prototype.
• Tous les membres de l'entreprise qui en ont besoin doivent avoir accès au prototype et à la documentation.
• Le client doit pouvoir accéder à la partie fonctionnelle du prototype pour les tests utilisateurs.
• Le prototype doit remplacer la spécification et fonctionner au plus près de la fonctionnalité prévue sans câbler un produit fini.
• Il doit être facile d'apporter et d'enregistrer des modifications au prototype.
• Il devrait être facile de créer des variantes A/B pouvant être testées par toute personne ayant accès au prototype.
• Il devrait être facile d'exporter la documentation client à partir du prototype.

Présentation de StopLight

L'outil que j'utilise et qui satisfait presque tout ce qui précède s'appelle Stoplight.io . Il s'agit essentiellement d'un moteur de documentation d'API et d'un proxy Web. Il vous permet de définir votre API à l'aide d'une interface utilisateur intuitive, qui possède le meilleur de Swagger et de RAML dans les coulisses comme moteur de spécification, ainsi que la possibilité d'importer ou d'exporter à partir de l'un ou l'autre format.

Étant donné que StopLight est un outil de documentation, vous pouvez définir les demandes, les réponses, les en-têtes et les descriptions de vos points de terminaison. Avec la fonctionnalité de proxy, vous pouvez appeler votre API et vérifier que vos appels correspondent à vos spécifications ou découvrir automatiquement vos points de terminaison pour que la plupart de votre documentation soit écrite automatiquement.

Le proxy de StopLight possède également plusieurs autres fonctionnalités absolument incroyables :

• La possibilité de faire des appels fictifs à vos points de terminaison si votre produit n'est pas terminé ou si vous ne souhaitez pas transmettre vos demandes par proxy.
• Serveur local pour tester votre prototype sur votre machine.
• Serveur distant pour tester votre prototype sur Internet.
• Middleware, écrit en Javascript, pour définir le code qui peut s'exécuter avant et/ou après l'appel des points de terminaison de votre prototype.

Si vous comparez la combinaison de ma liste de souhaits, les exigences de spécification de Cagan et sa liste de souhaits à la fonctionnalité fournie par StopLight, vous pouvez voir que StopLight répond à tous les besoins et désirs :

• Documentation interne uniquement du prototype et de ses fonctionnalités.
• Un prototype complet facilement accessible de la fonctionnalité.
• Une interface testable qui a la capacité de basculer des fonctionnalités variables pour les tests et les commentaires des utilisateurs.
• Un moyen simple de versionner votre prototype pour une conversation spécifique, afin que vous puissiez modifier la fonctionnalité du prototype en temps quasi réel pour illustrer et vérifier les commentaires que vous avez reçus.

Le flux de travail dans StopLight est simple et peut être effectué par n'importe qui , quelle que soit sa capacité technique :

• Créez un nouveau projet.
• Ajoutez la spécification en cliquant et en saisissant des informations sur le point de terminaison, ses paramètres, sa demande et sa réponse.
• Ajoutez les informations de spécification concernant votre prototype dans l'écran Définition.
• Si vous avez des fonctionnalités facultatives, ajoutez-les à l'aide du middleware.
• Activez la moquerie.
• Copiez/collez l'URL publique du serveur moqueur et partagez-la pour obtenir des commentaires.

Si vous rendez visite à un client et souhaitez expérimenter le prototype en temps réel, téléchargez simplement la définition sur votre ordinateur, créez un nouveau projet nommé d'après votre visite et importez la définition. Maintenant, vous pouvez changer tout ce que vous voulez sans changer votre prototype d'origine. Lorsque vous êtes de retour et que vous fusionnez des idées, il est aussi facile d'apporter des modifications que de construire le prototype en premier lieu.

En tant que responsable produit de l'expérience développeur, StopLight m'aide non seulement à faire mon travail plus efficacement, mais il est extrêmement simple à utiliser et facilite les étapes de préparation de la livraison de la documentation de l'API, car la documentation a été lancée avant les étapes de validation client et est mise à jour. tout au long du processus. Il existe de nombreux autres cas d'utilisation et fonctionnalités fournis par StopLight, mais c'est peut-être celui qui a eu le plus d'impact sur mon travail.

*Les exigences et la liste de souhaits de Cagan sont des citations directes de Inspired: How to Build Products Customers Love.