 Bienvenue, nous avons Rudi ici, nous montrant comment nous évoquer des documents pour mieux les APIs. Je lui donne un petit clap. Bonjour. Je suis Rodi, je travaille à Criteo, une compagnie qui délivre des ades personnellistes à Skate. Mon équipe est construit un outil de monitoring pour notre large outil de software et d'advoins. Et parfois, il y a des temps que nous avons décidé de faire des ades personnellistes et de commencer à expérimenter les différents ades sur le service web et les APIs browser. Cette présentation nous donne une glisse de ce que nous avons fait. Et c'est un travail joint avec mon collègue, Hugo Robour, qui est là. Je l'ai oublié. Alors, quel est l'application de browser? Évidemment, c'est composé de deux mots, les mots browser. Probablement, c'est lié à un browser. Et plus importantement, c'est lié à l'exploration et à l'expérimentation. Et je vais l'ajouter plus tard. Et il y a un nom de l'application. Nous allons parler de formules. Donc, un API est une sorte d'application. Il peut être très explicite, comme si tu déclasais une specification swagueur. Ou il peut être explicite, comme dans la documentation. Le contracte, il définit l'utilisation valide du service qui est lié à l'application. Même si l'opération est liée à l'application et aussi à l'utilisation valide pour l'opération dans le service. Pourquoi est-ce intéressant? Parce que ça donne beaucoup de features pour votre service. Donc, la première feature que je vais parler de est pourquoi nous poursuivons de la documentation pour décrire l'application. Ensuite, je vais parler de des features basiques que tu as dans l'application. Donc, la première feature basique est l'explorabilité. Ça veut dire que tu peux aller à l'application et demander ce que l'opération est possible sur l'application. Donc, ici, tu as un view d'un application avec différentes opérations. Et ensuite, tu peux juste cliquer sur l'opération et tu vois la documentation de l'opération, les paramètres types et ce sont les besoins possibles. Et ensuite, plus que ça, tu peux jouer avec l'opération. Donc, tu dois tiper l'input de l'opération et le coller. Et donc, tu peux voir quelle est la réponse et explorer le comportement de cette opération. Mais toujours, le type d'input comme l'input de l'input peut être difficile. Donc, on peut probablement faire quelque chose de mieux. Un autre très important feature d'un API est d'inforcer la validation de l'input de l'input et de l'input. D'ailleurs, cette opération s'occupe de l'input de l'input de l'input. Tu n'as pas besoin d'une opération d'utiliser d'un médecin c'est pourquoi tu devrais valider les impôts de ton service. Si une liste est transmissée en lieu de un string, personne ne sait que le code va s'occuper dans ce cas. Et même pour les impôts du JSON, tu peux avoir une conversion entre l'input de la JSON et entre vos types de Python. OK, ceci est un feature évident. Comme je l'ai dit avant, il peut être vraiment malade d'entrer la data JSON parce que c'est un format de verbe. Donc, avoir des formes fait que vous savez des temps. Et ça donne à l'input de client de l'input de validation sur la table. Et un autre très intéressant feature est que vous avez ce type de contract. Et vous avez votre service implementation. Et vous voulez être sûrs qu'ils sont parfaitement matchs. Donc, ça serait vraiment cool de juste demander aux tests automatiques pour vérifier que c'est match. Et je vais aussi présenter un autre feature qui fait que l'appli bros est plus user-friendly. Et le dernier, juste pour mentionner, vous pouvez vouloir générer, même si vous utilisez le doc, un construct plus formal, comme dans Swagger. Parce que Swagger a beaucoup d'aménages features que vous pouvez l'utiliser plus tard. Et c'est le plan de la table, le doc, en fait. Donc, je commence maintenant. Imaginez que vous voulez ajouter une nouvelle fonction sur votre API. Qu'est-ce que vous faites? OK, c'est facile. Vous documentez les fonctions. Et vous ajoutez le décorateur public. Donc, ce décorateur, vous résistez la fonction comme une opération dans l'appli. La fonction sera élevé et modifiée. Donc, vous pouvez encore l'utiliser comme avant quand le décorateur n'était pas là. Et derrière les scènes, la fonction sera rapide dans l'appli où tous les détails sur l'HCTP seraient basés. Donc, ou est-ce que c'est fini? La documentation sera passée. Donc, nous avons l'information sur l'input, l'input et les exceptions. Cela vous donne un constat de type sur l'input, l'input et possible 0. Et aussi, la signature des fonctions donne une valeur default pour l'input. Donc, ici, nous avons un constat de type. C'est ce qu'il y a dans les cartes. Les constats de type sont plus qu'un type. Ils peuvent être paramétriques pour les types de mapping. Ici, nous avons une liste de paramétriques qui sont paramétriques par MyTipB. Ou on peut également contacter plusieurs types de names, comme le premier paramétre, c'est un int ou un swing. Et par ces types de constats, nous pouvons trouver que tous les inputs seraient validés et transmis à un objectif de Python. Pour cela, nous avons converti ce type en suite dans un schema JSON. Pour ceux qui ne connaissent pas ce que sont les formats JSON et JSON, un objectif JSON peut être vu comme un subset de la pièce de Python. Donc, souvent, la conversion entre les deux est libre. Mais pour vos services, vous devez toujours faire une validation additionnelle. Et cela est fait par un schema JSON. Donc, quel est le schema JSON ? Un schema JSON décrive la structure de l'objectif JSON comme les types ou les valeurs minimales ou ce qu'il contient. Comme le nom de la pièce, ce qui est optionnel, cela décrive ce que vous espérez d'un input. Et il y a aussi une situation où vous voulez une conversion réelle donc vous avez un dictionary JSON et vous voulez être converti à votre propre pièce de Python. Donc, pour ces deux cas, quand vous voulez avoir une validation additionnelle et une conversion custom, nous introduisons deux classes qui permettent d'attacher la conversion et le schema JSON à votre classe régulière. Donc, de cela, nous pouvons obtenir un schema JSON d'un type de contrainte. Donc, quelle est la validation et la conversion ? Quand le service est appelé et que l'input est reçu, il y a la première validation pour la plus basée validation nous réalisons un type de contrainte dans le document. Et pour une plus complexe, nous réalisons ce schema JSON. Donc, il y a un library qui s'appelle JSON schema que vous pouvez utiliser pour valider la structure de votre schema JSON. Après cette validation, il y a une conversion qui est impliquée pour le type de la plus basée ou le type de contrainte en utilisant le JSON de la classe. Et ensuite, la function réelle est appelée et de cela, il peut être deux outils. Vous pouvez avoir des exceptions. Et donc, ce que nous faisons, c'est que nous vérifions que les exceptions respectent le contract. Si ce n'est pas le contenu de l'exception de l'usage de la service pour voir si quelque chose n'est pas accepté par le contract. Et puis, si nous obtenons un résultat de cette fonction, nous validons ce type. Qu'est-ce qu'on peut faire avec JSON schema ? Après tout, c'est sondage. Vous pouvez utiliser JSON editor pour utiliser un schema de JSON pour générer une forme qui est également un editor. Et c'est capable de validation de la forme et de vous donner de la valeur de JSON. Donc, vous avez juste de plug-in un appel à JSON editor dans votre formule HTML et vous avez un cool feature pour presque rien. Donc, ici, vous avez une vue de ce que vous avez avant. Vous devez mettre le contenu de JSON dans le texte avec moi. Et non, en utilisant JSON editor vous avez juste de la forme, donc c'est vraiment facile de créer un input. Ce n'est pas que il y a un similar feature qui devrait aussi en ce cas, déclarer les choses manuellement, comme le serialisateur pour la forme, juste comme vous devez mettre un JSON pour un schema. Donc, qu'est-ce qu'on peut faire avec JSON schema ? Je ne sais pas si vous connaissez un package nommé hypothesis. C'est un package qui vous aide à faire le base property donc, c'est une stratégie qu'on peut générer des inputs pour beaucoup d'usuales types. Et c'est vraiment fantastique, je vous encourage à l'utiliser. Donc, on va ajouter la stratégie de JSON schema. Avec ça, on peut générer la stratégie de JSON et on peut vérifier que toutes les opérations de notre service respectent le contract décrivé par la documentation. Donc, ici, j'ai pris deux exemples. J'ai pris un code valide qui respecte le contract juste avant. J'ai pris une exception. J'ai ajouté le type R. J'ai eu l'internation. Et de l'automatique test, nous avons ce message où, le type R est découvert et il est montré par le développeur avec un propre stack trace. Et second, le programmeur est aussi un de l'exception qui est décrivée par le contract. Il n'est jamais occupé par cette opération. Donc, il montre que ce qui est décrivé par la documentation pourrait être ordinate, par exemple. Et ensuite, j'ai pris un autre exemple où j'ai modifié le code valide et j'ai fait le retour de la valeur. C'est comme un liste pour une fonction qui est expérimentée par quelque chose d'autre. Et donc, ce qu'on voit c'est que c'est aussi détecté automatiquement. Donc, nous avons quelque chose qui est capable de prendre votre API et automatiquement que ce que vous avez décrivé par la documentation est en part avec la compétition de la compétition. Ce qui est un très cool fonctionnement. Donc, ce que je peux faire avec le schema JSON ? Je ne sais pas, on ne s'est pas arrêté. Donc, nous avons déjà un moyen d'interpréter les formes. Est-ce que nous pouvons avoir quelque chose utile de la compétition JSON ? Donc, en taking inspiration de la chaine Django qui a déjà fait la couleur de la compétition JSON, nous avons décidé d'aller plus loin pour ajouter quelque chose qu'on appelle Prative View. Donc, Prative View, ça vous aide à définir la visualisation custom de la compétition JSON. Donc, ici, pour l'instant, vous avez le overview bas sur la Prative View dans la partie de l'écran. Et vous pouvez voir que le JSON contient un timestamp. Et dans la Prative View, le timestamp est converti directement à un date humain et il y a aussi un autre exemple où vous avez une valeur intérieure dans le JSON, et il a une particularité sémantique. Et la Prative View est capable de montrer cette sémantique. Donc, ici, c'est la valeur 0 qui est un ok flag. Donc, ça fait vraiment la réponse JSON plus facile à lire pour les humains. Et autre chose que nous avons ajouté à la Prative View c'est l'obligation pour ajouter de l'information extrême. Comme ici, la Prative View dit quelque chose d'actifs dans les temps qui ne sont pas en réponse initiale. Et plus en plus, il y a un lien à cette information extrême. Et qui est appelé l'input lien. C'est un lien qui est capable d'aller dans une autre opération et de profiler toute l'information dans la forme. Donc, vous pouvez naviguer entre différents features dans l'API. Et vous n'avez pas à cliquer. Donc ici, quand vous cliquez sur le lien red, vous allez sur la page d'opération et d'autres pages d'opération. Tout le lien sera déjà prouvé. Alors, qu'est-ce qu'il y a? Nous planterons d'ouvrir toutes les choses que nous avons présentées. Donc, vous pouvez regarder le critéo-github-repository. Nous allons ajouter des contributions différentes. Nous allons aussi contribuer à l'hypothèse avec la stratégie de Gisan schema. Et une chose que nous n'avons pas fait et qui pourrait être très intéressante c'est de soutenir énormément naturellement parce que c'est un endroit intéressant. Et d'intégrer plus avec les tests. Parce que la chose que je vous montre, qui vous donnait un diagnostic pour votre API, avec les warnings et les erreurs du mismatch entre le construct et l'implementation, maintenant, vous devez l'enlever et ça serait mieux d'intégrer les tests standard. Ensuite, il y a la génération swagger spec. Donc, nous avons déjà beaucoup de cool features. Pourquoi nous avons besoin de ça? Parce que swagger a la possibilité de générer un code client, un code library. C'est-à-dire que vous coudrez votre service en Python et puis vous voulez que les gens puissent avoir l'accessibilité automatique en Java. Vous avez juste écrit le file swagger et ça va générer le client pour vous en Java. C'est vraiment une bonne chose. Donc, si vous avez juste un message simple de cette présentation, possible API, il y a beaucoup d'interessants de choses parce qu'ils sont très user-friendly et vous pouvez découvrir le contenu et explorer et tester. C'est très bon. La documentation et les types peuvent être vraiment utilisés pour ajouter beaucoup de features pour votre service. Donc, ici, je vais vous donner quelques exemples de la présentation mais il y a beaucoup plus de choses à faire. Et aussi, la construction, Json et Json schema. Ils sont très dents. Ils sont standard. Il y a beaucoup de tools donc n'hésitez pas à les utiliser. Je pense que ça va vous aider à avoir de nouvelles features dans votre code. Et c'est tout. Si vous avez des questions. Questions ? Merci d'être venus.