Dans ce manifeste, nous allons donner une définition précise de ce que REST est, selon Roy,\net voir la majorité des API et spécifications API (JSONAPI, HAL, etc.) ne pas suivre ce modèle.\nNous verrons quels problèmes une API RESTful apporte et pourquoi les concepteurs d’API sont constamment\nen évitant de l’utiliser, mais en proposant des solutions à mi-parcours ou un repli sur des solutions alternatives.\ndes modèles tels que RPC sur HTTP ou, récemment, GraphQL.\nEnsuite, nous proposerons un nouveau modèle, REST Introspected,\nqui résout les problèmes créés par REST et permet la conception d’API évolutives,\nde manière beaucoup plus simple que REST conventionnel.\nDans le cadre de ce manifeste, nous présenterons également le concept de MicroTypes,\npetits modules réutilisables qui composent un type de support et facilitent son évolution\net extensibilité de notre nouveau modèle.\nPour la mise en œuvre de notre nouveau modèle en HTTP, il faudra remonter dans le temps,\napprofondir les RFC existantes et découvrir des concepts oubliés, tels que le contenu réactif\nparamètres de négociation et de type de média, afin de plier le réseau Internet existant\nl'infrastructure, qui a été principalement influencée par les concepts REST, et a appliqué avec succès notre nouveau modèle.\n1. Définitions\nTout d’abord, quelques définitions que nous utiliserons dans le texte:
"},{"id":"text-2","type":"text","heading":"","plain_text":"DU REPOS, Reposant: Le modèle que Roy a défini dans sa thèse (avec son API de post de blog doit être piloté par hypertexte).\nLe reste: API qui suivent tous les modèles de pièces REST, sauf HATEOAS dans lequel ils supportent principalement des liens (spécifications telles que JSONAPI, HAL, etc.)\nAgité: API ayant une API JSON simple sans aucun lien (suit un modèle REST autre que HATEOAS)\nREST Introspecté: Les API qui suivent la définition du modèle que nous fournissons dans cette manifeste","html":"DU REPOS, Reposant: Le modèle que Roy a défini dans sa thèse (avec son API de post de blog doit être piloté par hypertexte).\nLe reste: API qui suivent tous les modèles de pièces REST, sauf HATEOAS dans lequel ils supportent principalement des liens (spécifications telles que JSONAPI, HAL, etc.)\nAgité: API ayant une API JSON simple sans aucun lien (suit un modèle REST autre que HATEOAS)\nREST Introspecté: Les API qui suivent la définition du modèle que nous fournissons dans cette manifeste
"},{"id":"text-3","type":"text","heading":"","plain_text":"Nous utiliserons le terme API et API en réseau de manière interchangeable.\n2. Introduction\nREST défini par Roy était un travail magnifique, très en avance sur son temps\nce qui nous a pris de nombreuses années pour comprendre quelles sont ses capacités.\nCependant, presque 20 ans plus tard, le modèle REST montre son âge. C’est inflexible,\ndifficile à mettre en œuvre, difficile à tester, avec des problèmes de performance et de mise en œuvre.\nMais le plus important, toute implémentation du modèle REST est très complexe.\nMaintenant, on pourrait dire que la plupart des API ne sont pas conçues pour durer des décennies et peut-être\nC’est la raison pour laquelle ce modèle n’a pas été très adopté.\nLe premier est vrai, mais même si le dernier est aussi vrai, cela pourrait-il signifier que ce modèle est\nne convient pas aux API à court terme?\nNous croyons fermement que REST est bien meilleur que toute API qui ne suit pas DU REPOS des principes\n(comme les API RESTly), même pour les API à court terme.\nLes services en réseau ont des caractéristiques très particulières que, jusqu'à présent, seuls REST et GraphQL les ont entièrement pris en charge.\nIl est essentiel de pouvoir faire évoluer notre API sans casser les clients.\nImaginez le scénario suivant: nous avons créé un réseau social en ligne et une application iOS qui communique avec l'API sur notre backend.\nMaintenant, imaginez qu’après une réunion d’entreprise, notre PDG ait besoin que nous apportions des modifications minimes mais importantes à la page d’inscription: demandez à l’utilisateur\npour remplir son âge, un champ du formulaire d'inscription que nous n'avions pas auparavant.\nCela signifie essentiellement, en termes d'API, ajouter un champ supplémentaire dans l'objet accepté et obliger le client à le renseigner.\npar l'utilisateur avant de l'envoyer.\nSi notre API est RESTly et non REST, cela signifie que nous devons corriger le code côté iOS, le tester et envoyer une nouvelle application iOS à Apple Store.\nIl faut environ une semaine à Apple pour examiner notre application. Si, pour une raison quelconque, notre application n’est pas rejetée pendant le processus de révision, notre\npetit changement prendra des mesures au moins une semaine plus tard après la demande.\nSi notre API était REST, cela signifierait un simple changement dans la réponse du serveur, indiquant quels champs sont requis pour soumettre le formulaire.\nLe changement serait déployé 10 minutes plus tard.\nRoy note dans sa thèse:","html":"Nous utiliserons le terme API et API en réseau de manière interchangeable.\n2. Introduction\nREST défini par Roy était un travail magnifique, très en avance sur son temps\nce qui nous a pris de nombreuses années pour comprendre quelles sont ses capacités.\nCependant, presque 20 ans plus tard, le modèle REST montre son âge. C’est inflexible,\ndifficile à mettre en œuvre, difficile à tester, avec des problèmes de performance et de mise en œuvre.\nMais le plus important, toute implémentation du modèle REST est très complexe.\nMaintenant, on pourrait dire que la plupart des API ne sont pas conçues pour durer des décennies et peut-être\nC’est la raison pour laquelle ce modèle n’a pas été très adopté.\nLe premier est vrai, mais même si le dernier est aussi vrai, cela pourrait-il signifier que ce modèle est\nne convient pas aux API à court terme?\nNous croyons fermement que REST est bien meilleur que toute API qui ne suit pas DU REPOS des principes\n(comme les API RESTly), même pour les API à court terme.\nLes services en réseau ont des caractéristiques très particulières que, jusqu'à présent, seuls REST et GraphQL les ont entièrement pris en charge.\nIl est essentiel de pouvoir faire évoluer notre API sans casser les clients.\nImaginez le scénario suivant: nous avons créé un réseau social en ligne et une application iOS qui communique avec l'API sur notre backend.\nMaintenant, imaginez qu’après une réunion d’entreprise, notre PDG ait besoin que nous apportions des modifications minimes mais importantes à la page d’inscription: demandez à l’utilisateur\npour remplir son âge, un champ du formulaire d'inscription que nous n'avions pas auparavant.\nCela signifie essentiellement, en termes d'API, ajouter un champ supplémentaire dans l'objet accepté et obliger le client à le renseigner.\npar l'utilisateur avant de l'envoyer.\nSi notre API est RESTly et non REST, cela signifie que nous devons corriger le code côté iOS, le tester et envoyer une nouvelle application iOS à Apple Store.\nIl faut environ une semaine à Apple pour examiner notre application. Si, pour une raison quelconque, notre application n’est pas rejetée pendant le processus de révision, notre\npetit changement prendra des mesures au moins une semaine plus tard après la demande.\nSi notre API était REST, cela signifierait un simple changement dans la réponse du serveur, indiquant quels champs sont requis pour soumettre le formulaire.\nLe changement serait déployé 10 minutes plus tard.\nRoy note dans sa thèse:
"},{"id":"text-4","type":"text","heading":"","plain_text":"Un système qui se veut aussi durable que le Web doit être préparé au changement\n– Roy Fielding","html":"Un système qui se veut aussi durable que le Web doit être préparé au changement\n– Roy Fielding
"},{"id":"text-5","type":"text","heading":"","plain_text":"Dans le monde des startups et des entreprises axées sur l'argent, les éléments suivants seront plus attrayants:","html":"Dans le monde des startups et des entreprises axées sur l'argent, les éléments suivants seront plus attrayants:
"},{"id":"text-6","type":"text","heading":"","plain_text":"Si vous souhaitez agir rapidement, vous devez créer une API axée sur le changement en premier.","html":"Si vous souhaitez agir rapidement, vous devez créer une API axée sur le changement en premier.
"},{"id":"text-7","type":"text","heading":"","plain_text":"Une API qui peut changer l'état du client sans avoir à changer ce dernier.\nÉtant donné que, comment pouvons-nous avoir un modèle plus simple que REST, tout en tirant la même, sinon plus, fonctionnalité de\nDU REPOS?\nComme nous le montrerons, Introspected REST est un style architectural API qui résout ce problème.\nUn style architectural n’est pas une implémentation et ce n’est pas non plus une spécification.\nComme le note Roy:","html":"Une API qui peut changer l'état du client sans avoir à changer ce dernier.\nÉtant donné que, comment pouvons-nous avoir un modèle plus simple que REST, tout en tirant la même, sinon plus, fonctionnalité de\nDU REPOS?\nComme nous le montrerons, Introspected REST est un style architectural API qui résout ce problème.\nUn style architectural n’est pas une implémentation et ce n’est pas non plus une spécification.\nComme le note Roy:
"},{"id":"text-8","type":"text","heading":"","plain_text":"Un style architectural est un ensemble coordonné de contraintes architecturales qui limite\n les rôles / caractéristiques des éléments architecturaux et les relations autorisées entre ceux-ci\n éléments de toute architecture conforme à ce style.\n– Roy Fielding","html":"Un style architectural est un ensemble coordonné de contraintes architecturales qui limite\n les rôles / caractéristiques des éléments architecturaux et les relations autorisées entre ceux-ci\n éléments de toute architecture conforme à ce style.\n– Roy Fielding
"},{"id":"text-9","type":"text","heading":"","plain_text":"Introspected REST est basé sur le modèle initial de Roy, mais élimine le besoin de runtime HATEOAS.\nAu lieu de cela, le client dérive l'état à la demande, en utilisant l'introspection, en récupérant les métadonnées nécessaires.\nqui sont d'intérêt.\nFinalement, cela apporte les mêmes avantages que le modèle de Roy, tout en étant beaucoup plus simple,\nbeaucoup plus souple et compatible avec toutes les API RESTly ou RESTless.\nMais parlons d’abord des services en réseau.\n3. Services en réseau et API\nAujourd'hui, JSON est devenu si populaire que les développeurs oublient presque qu'il existe un tas de\nprotocoles en dessous.\nLes développeurs oublient également que JSON n'est qu'une spécification au niveau du message, comme XML.\nCe n’est pas le seul et ce n’est certainement pas le meilleur que nous puissions utiliser.\nNéanmoins, c’est simple et la simplicité est une vertu.\nBien que le modèle OSI soit le modèle conceptuel que nous utilisons pour décrire les réseaux informatiques,\navec TCP / IP suivant 5 couches d’abstraction OSI sur 7, dans notre cas, nous en ferons une description plus spécifique à l’API.\nLorsque nous souhaitons demander une ressource à une API hypermédia en réseau, nous grossièrement\navoir les niveaux suivants:\n3.1. Niveau d'application\nAu niveau de l’application, le client commence la négociation du contenu (ou la sélection du contenu), généralement en demandant\npour un seul type de support.\nUn type de support fournit des informations sur la structure du contenu et le format du message utilisé dans les données qu'il décrit.\ncomme décrit par la RFC 2046.\nDans le protocole HTTP, la négociation du contenu est réalisée par un client à l'aide de l'en-tête Accept qui indique les types de support qu'il\npeut comprendre, dans un ordre de préférence.\nEnsuite, le serveur répond avec un type de support proposé par le client dans l'en-tête Content-Type.\napplication / json est un type de support qui indique que le format de données de la demande\nla représentation est au format de données JSON.\nPlus précisément, le type de ce type de support est application tandis que le sous-type est JSON.\nJSON lui-même n'est pas un type de support mais un format de message.\nLes types de support peuvent également être un peu plus complexes: application / vnd.api + json, le type de support de la spécification JSONAPI, signifie (à peu près) que","html":"Introspected REST est basé sur le modèle initial de Roy, mais élimine le besoin de runtime HATEOAS.\nAu lieu de cela, le client dérive l'état à la demande, en utilisant l'introspection, en récupérant les métadonnées nécessaires.\nqui sont d'intérêt.\nFinalement, cela apporte les mêmes avantages que le modèle de Roy, tout en étant beaucoup plus simple,\nbeaucoup plus souple et compatible avec toutes les API RESTly ou RESTless.\nMais parlons d’abord des services en réseau.\n3. Services en réseau et API\nAujourd'hui, JSON est devenu si populaire que les développeurs oublient presque qu'il existe un tas de\nprotocoles en dessous.\nLes développeurs oublient également que JSON n'est qu'une spécification au niveau du message, comme XML.\nCe n’est pas le seul et ce n’est certainement pas le meilleur que nous puissions utiliser.\nNéanmoins, c’est simple et la simplicité est une vertu.\nBien que le modèle OSI soit le modèle conceptuel que nous utilisons pour décrire les réseaux informatiques,\navec TCP / IP suivant 5 couches d’abstraction OSI sur 7, dans notre cas, nous en ferons une description plus spécifique à l’API.\nLorsque nous souhaitons demander une ressource à une API hypermédia en réseau, nous grossièrement\navoir les niveaux suivants:\n3.1. Niveau d'application\nAu niveau de l’application, le client commence la négociation du contenu (ou la sélection du contenu), généralement en demandant\npour un seul type de support.\nUn type de support fournit des informations sur la structure du contenu et le format du message utilisé dans les données qu'il décrit.\ncomme décrit par la RFC 2046.\nDans le protocole HTTP, la négociation du contenu est réalisée par un client à l'aide de l'en-tête Accept qui indique les types de support qu'il\npeut comprendre, dans un ordre de préférence.\nEnsuite, le serveur répond avec un type de support proposé par le client dans l'en-tête Content-Type.\napplication / json est un type de support qui indique que le format de données de la demande\nla représentation est au format de données JSON.\nPlus précisément, le type de ce type de support est application tandis que le sous-type est JSON.\nJSON lui-même n'est pas un type de support mais un format de message.\nLes types de support peuvent également être un peu plus complexes: application / vnd.api + json, le type de support de la spécification JSONAPI, signifie (à peu près) que
"},{"id":"text-10","type":"text","heading":"","plain_text":"le type principal est application\nle sous-type est vnd.api lequel grossièrement dénote le nom du type de média\nla structure sous-jacente suit la sémantique JSON","html":"le type principal est application\nle sous-type est vnd.api lequel grossièrement dénote le nom du type de média\nla structure sous-jacente suit la sémantique JSON
"},{"id":"text-11","type":"text","heading":"","plain_text":"En théorie, la sémantique des spécifications JSONAPI pourrait également être appliquée en utilisant XML comme format de données (comme dans le cas de HAL),\nou même YAML, mais en pratique, nous avons tendance à l'oublier et nous traitons tous les types de supports comme uniques et non composites.\nCependant, il convient également de noter que le Les types de média et la négociation de contenu en général sont\nnon limité à HTTP seulement.\nBien que HTTP soit l’un des protocoles de réseau d’applications les plus populaires à l’heure actuelle, la même logique pourrait être appliquée.\ndans d'autres protocoles (principalement textuels) tels que SIP, CoAP, QUIC, etc.\nEn résumé, la sémantique au niveau de l'application est définie par le type de média demandé et ne doit pas être étroitement couplée à la sémantique du\nniveau du message (comme JSON) ou le niveau de protocole sous-jacent (comme HTTP).\n3.2. Niveau du message\nAu niveau du message, nous trouvons le format utilisé pour la représentation réelle.\nAujourd’hui, nous avons presque mélangé le niveau de message avec JSON, mais dans la pratique,\nformats pourraient être utilisés avec succès: XML, YAML, TOML pour en nommer quelques-uns.\nLe format de message utilisé est généralement décrit par le suffixe du type de support.\n3.3. Niveau de protocole\nAu niveau du protocole, les demandes sont généralement envoyées à l'aide du protocole HTTP.\nAprès tout, de nos jours, la majeure partie du développement se fait sur le Web et\nHTTP est le seul protocole officiellement pris en charge par les navigateurs.\nNéanmoins, il existe également d'autres protocoles similaires sans état.\nQUIC est un protocole alternatif HTTP ciblé pour une faible latence et utilise UDP.\nsous.\nCoAP est ciblé dans l'IdO et utilise également UDP en dessous (la pile TCP / IP complète est assez lourde pour les périphériques à contraintes).\nSIP est également un protocole textuel avec la même sémantique que HTTP et est utilisé en VoIP.\n3.4. Niveau réseau\nEnfin, au niveau du réseau, le navigateur (ou tout autre client autre que le navigateur) envoie la requête en réseau.\ndans l'un des TCP, UDP, etc.\nLe protocole réel dépend du protocole utilisé au niveau du protocole.\n4. Modèle REST de Roy\nRoy a mis au point le modèle REST afin de résoudre les problèmes liés aux propriétés uniques des services en réseau.\npendant la petite enfance d'Internet.\nLorsque nous développons une application qui sera déployée dans un environnement réseau et que d’autres services en réseau devraient y accéder,\nnous devons réfléchir à son évolutivité:\nsi nous devons ajouter, supprimer ou modifier les fonctionnalités de cette application\nnous ne pouvons pas nous attendre à ce que les services à l'autre bout parlent avec notre application d'être mis à jour par des humains.\nDe tels problèmes résultant des particularités des réseaux, tels que la découverte et l’évolutivité, doivent être résolus en utilisant\ncommunication machine à machine.\nLe modèle REST qui résout de tels problèmes est un style architectural qui n'est lié à aucune spécification, protocole ou format de la\nles niveaux susmentionnés.","html":"En théorie, la sémantique des spécifications JSONAPI pourrait également être appliquée en utilisant XML comme format de données (comme dans le cas de HAL),\nou même YAML, mais en pratique, nous avons tendance à l'oublier et nous traitons tous les types de supports comme uniques et non composites.\nCependant, il convient également de noter que le Les types de média et la négociation de contenu en général sont\nnon limité à HTTP seulement.\nBien que HTTP soit l’un des protocoles de réseau d’applications les plus populaires à l’heure actuelle, la même logique pourrait être appliquée.\ndans d'autres protocoles (principalement textuels) tels que SIP, CoAP, QUIC, etc.\nEn résumé, la sémantique au niveau de l'application est définie par le type de média demandé et ne doit pas être étroitement couplée à la sémantique du\nniveau du message (comme JSON) ou le niveau de protocole sous-jacent (comme HTTP).\n3.2. Niveau du message\nAu niveau du message, nous trouvons le format utilisé pour la représentation réelle.\nAujourd’hui, nous avons presque mélangé le niveau de message avec JSON, mais dans la pratique,\nformats pourraient être utilisés avec succès: XML, YAML, TOML pour en nommer quelques-uns.\nLe format de message utilisé est généralement décrit par le suffixe du type de support.\n3.3. Niveau de protocole\nAu niveau du protocole, les demandes sont généralement envoyées à l'aide du protocole HTTP.\nAprès tout, de nos jours, la majeure partie du développement se fait sur le Web et\nHTTP est le seul protocole officiellement pris en charge par les navigateurs.\nNéanmoins, il existe également d'autres protocoles similaires sans état.\nQUIC est un protocole alternatif HTTP ciblé pour une faible latence et utilise UDP.\nsous.\nCoAP est ciblé dans l'IdO et utilise également UDP en dessous (la pile TCP / IP complète est assez lourde pour les périphériques à contraintes).\nSIP est également un protocole textuel avec la même sémantique que HTTP et est utilisé en VoIP.\n3.4. Niveau réseau\nEnfin, au niveau du réseau, le navigateur (ou tout autre client autre que le navigateur) envoie la requête en réseau.\ndans l'un des TCP, UDP, etc.\nLe protocole réel dépend du protocole utilisé au niveau du protocole.\n4. Modèle REST de Roy\nRoy a mis au point le modèle REST afin de résoudre les problèmes liés aux propriétés uniques des services en réseau.\npendant la petite enfance d'Internet.\nLorsque nous développons une application qui sera déployée dans un environnement réseau et que d’autres services en réseau devraient y accéder,\nnous devons réfléchir à son évolutivité:\nsi nous devons ajouter, supprimer ou modifier les fonctionnalités de cette application\nnous ne pouvons pas nous attendre à ce que les services à l'autre bout parlent avec notre application d'être mis à jour par des humains.\nDe tels problèmes résultant des particularités des réseaux, tels que la découverte et l’évolutivité, doivent être résolus en utilisant\ncommunication machine à machine.\nLe modèle REST qui résout de tels problèmes est un style architectural qui n'est lié à aucune spécification, protocole ou format de la\nles niveaux susmentionnés.
"},{"id":"text-12","type":"text","heading":"","plain_text":"une API RESTful n'est qu'un site Web pour les utilisateurs dont le vocabulaire est limité (interaction machine à machine)\n– Roy Fielding","html":"une API RESTful n'est qu'un site Web pour les utilisateurs dont le vocabulaire est limité (interaction machine à machine)\n– Roy Fielding
"},{"id":"text-13","type":"text","heading":"","plain_text":"Quand Roy parle de REST, il mentionne 5 propriétés cruciales de DU REPOS modèle:\n4.1. Les méthodes d'accès ont la même sémantique pour toutes les ressources","html":"Quand Roy parle de REST, il mentionne 5 propriétés cruciales de DU REPOS modèle:\n4.1. Les méthodes d'accès ont la même sémantique pour toutes les ressources
"},{"id":"text-14","type":"text","heading":"","plain_text":"induit visible, évolutif, disponible via des systèmes multicouches, des caches partageables et cachables","html":"induit visible, évolutif, disponible via des systèmes multicouches, des caches partageables et cachables
"},{"id":"text-15","type":"text","heading":"","plain_text":"L’absence de cohérence dans l’accès impliquerait que nous ne fournissions pas une interface générique mais\nnous avons des interfaces spécifiques aux ressources ou même aux objets.\nEn fait, une interface commune est l’une des parties les plus cruciales de REST: sans une interface uniforme commune\nil serait impossible de dériver REST.","html":"L’absence de cohérence dans l’accès impliquerait que nous ne fournissions pas une interface générique mais\nnous avons des interfaces spécifiques aux ressources ou même aux objets.\nEn fait, une interface commune est l’une des parties les plus cruciales de REST: sans une interface uniforme commune\nil serait impossible de dériver REST.
"},{"id":"text-16","type":"text","heading":"","plain_text":"La caractéristique centrale qui distingue le style architectural REST des autres\nstyles basés sur le réseau est l'accent mis sur une interface uniforme entre les composants.\nEn appliquant le principe de génie logiciel général à l’interface composant,\nl'architecture globale du système est simplifiée et la visibilité des interactions est améliorée.\nLes implémentations sont découplées des services qu’elles fournissent, ce qui encourage les opérateurs indépendants.\névolutivité. Le compromis, cependant, est qu'une interface uniforme dégrade l'efficacité,\npuisque les informations sont transférées sous une forme normalisée plutôt que sous une forme spécifique\naux besoins d’une application. L’interface REST est conçue pour être efficace pour\ntransfert de données hypermédia à gros grains, optimisation pour le cas classique du Web,\nmais aboutit à une interface qui n'est pas optimale pour d'autres formes d'interaction architecturale.\nPour obtenir une interface uniforme, plusieurs contraintes architecturales sont nécessaires pour guider le comportement des composants.\nREST est défini par quatre contraintes d'interface: identification des ressources; manipulation des ressources par\nreprésentations; messages auto-descriptifs; et hypermédia en tant que moteur de l'état de l'application.\n– Roy Fielding","html":"La caractéristique centrale qui distingue le style architectural REST des autres\nstyles basés sur le réseau est l'accent mis sur une interface uniforme entre les composants.\nEn appliquant le principe de génie logiciel général à l’interface composant,\nl'architecture globale du système est simplifiée et la visibilité des interactions est améliorée.\nLes implémentations sont découplées des services qu’elles fournissent, ce qui encourage les opérateurs indépendants.\névolutivité. Le compromis, cependant, est qu'une interface uniforme dégrade l'efficacité,\npuisque les informations sont transférées sous une forme normalisée plutôt que sous une forme spécifique\naux besoins d’une application. L’interface REST est conçue pour être efficace pour\ntransfert de données hypermédia à gros grains, optimisation pour le cas classique du Web,\nmais aboutit à une interface qui n'est pas optimale pour d'autres formes d'interaction architecturale.\nPour obtenir une interface uniforme, plusieurs contraintes architecturales sont nécessaires pour guider le comportement des composants.\nREST est défini par quatre contraintes d'interface: identification des ressources; manipulation des ressources par\nreprésentations; messages auto-descriptifs; et hypermédia en tant que moteur de l'état de l'application.\n– Roy Fielding
"},{"id":"text-17","type":"text","heading":"","plain_text":"Par la suite, les 4 contraintes suivantes, le noyau de REST, résultent des efforts déployés pour obtenir une interface uniforme entre différents composants.\n4.2. Toutes les ressources importantes sont identifiées par un mécanisme d'identificateur de ressource","html":"Par la suite, les 4 contraintes suivantes, le noyau de REST, résultent des efforts déployés pour obtenir une interface uniforme entre différents composants.\n4.2. Toutes les ressources importantes sont identifiées par un mécanisme d'identificateur de ressource
"},{"id":"text-18","type":"text","heading":"","plain_text":"induit une communication simple, visible, réutilisable et sans état","html":"induit une communication simple, visible, réutilisable et sans état
"},{"id":"text-19","type":"text","heading":"","plain_text":"Roy l'explique très bien dans sa thèse:","html":"Roy l'explique très bien dans sa thèse:
"},{"id":"text-20","type":"text","heading":"","plain_text":"Une ressource est un mappage conceptuel sur un ensemble d'entités et non sur l'entité qui correspond au mappage à un moment donné.\nPlus précisément, une ressource R est une fonction d’appartenance M variant dans le tempsR(t),\nqui pour le temps t mappe à un ensemble d’entités, ou valeurs, qui sont équivalentes.\nLes valeurs de l'ensemble peuvent être des représentations de ressources et / ou des identificateurs de ressources. […]\nCertaines ressources sont statiques dans le sens où, examinées à tout moment après leur création,\nils correspondent toujours au même ensemble de valeurs.\nD'autres ont un degré de variance élevé dans leur valeur au fil du temps.\nLa seule chose qui doit être statique pour une ressource est la sémantique du mappage,\npuisque la sémantique est ce qui distingue une ressource d’une autre.\n– Roy Fielding","html":"Une ressource est un mappage conceptuel sur un ensemble d'entités et non sur l'entité qui correspond au mappage à un moment donné.\nPlus précisément, une ressource R est une fonction d’appartenance M variant dans le tempsR(t),\nqui pour le temps t mappe à un ensemble d’entités, ou valeurs, qui sont équivalentes.\nLes valeurs de l'ensemble peuvent être des représentations de ressources et / ou des identificateurs de ressources. […]\nCertaines ressources sont statiques dans le sens où, examinées à tout moment après leur création,\nils correspondent toujours au même ensemble de valeurs.\nD'autres ont un degré de variance élevé dans leur valeur au fil du temps.\nLa seule chose qui doit être statique pour une ressource est la sémantique du mappage,\npuisque la sémantique est ce qui distingue une ressource d’une autre.\n– Roy Fielding
"},{"id":"text-21","type":"text","heading":"","plain_text":"4.3. Les ressources sont manipulées par l'échange de représentations","html":"4.3. Les ressources sont manipulées par l'échange de représentations
"},{"id":"text-22","type":"text","heading":"","plain_text":"induit simple, visible, réutilisable, en mémoire cache et évolutif (masquage d'informations)","html":"induit simple, visible, réutilisable, en mémoire cache et évolutif (masquage d'informations)
"},{"id":"text-23","type":"text","heading":"","plain_text":"La représentation que nous exposons à partir de notre API publique pourrait être totalement différente de\nnotre mise en œuvre en interne ou comment les données sont stockées dans notre base de données.\nCela pourrait aussi être la même chose.\nNéanmoins, le client attend et doit manipuler toute ressource à l'aide de la représentation.\nnous exposons.\n4.4. Les représentations sont échangées via des messages auto-descriptifs","html":"La représentation que nous exposons à partir de notre API publique pourrait être totalement différente de\nnotre mise en œuvre en interne ou comment les données sont stockées dans notre base de données.\nCela pourrait aussi être la même chose.\nNéanmoins, le client attend et doit manipuler toute ressource à l'aide de la représentation.\nnous exposons.\n4.4. Les représentations sont échangées via des messages auto-descriptifs
"},{"id":"text-24","type":"text","heading":"","plain_text":"induit visible, évolutif, disponible via des systèmes multicouches, des caches partageables et cachables\ninduit évolutif via une communication extensible","html":"induit visible, évolutif, disponible via des systèmes multicouches, des caches partageables et cachables\ninduit évolutif via une communication extensible
"},{"id":"text-25","type":"text","heading":"","plain_text":"Cela signifie que les données de la réponse doivent suivre le type de média que le client\ndemandé et comprend.\nÉtant donné que le client a négocié pour ce type de média, il devrait être capable d'analyser et de comprendre n'importe quelle partie de la réponse.","html":"Cela signifie que les données de la réponse doivent suivre le type de média que le client\ndemandé et comprend.\nÉtant donné que le client a négocié pour ce type de média, il devrait être capable d'analyser et de comprendre n'importe quelle partie de la réponse.
"},{"id":"text-26","type":"text","heading":"","plain_text":"L’interaction est sans état entre les demandes, les méthodes standard et les types de support sont utilisés pour\nindiquer la sémantique et échanger des informations, et les réponses indiquent explicitement la possibilité de mise en cache.\n– Roy Fielding","html":"L’interaction est sans état entre les demandes, les méthodes standard et les types de support sont utilisés pour\nindiquer la sémantique et échanger des informations, et les réponses indiquent explicitement la possibilité de mise en cache.\n– Roy Fielding
"},{"id":"text-27","type":"text","heading":"","plain_text":"Si notre type de média est très faible (comme application / json) et nous avons besoin de fonctionnalités que le type de support ne décrit pas\nEnsuite, nous devons définir un autre type de support qui décrira la nouvelle sémantique et attendre que le ou les clients intègrent les nouvelles modifications du type de support.\nBriser la sémantique de notre type de support, ou simplement lui ajouter de nouvelles fonctionnalités, aura exactement le même résultat pour le client:\nmessages non descriptifs qui nécessiteront des informations hors bande, telles que la documentation.\n4.5 L'hypertexte en tant que moteur de l'état de l'application (HATEOAS)","html":"Si notre type de média est très faible (comme application / json) et nous avons besoin de fonctionnalités que le type de support ne décrit pas\nEnsuite, nous devons définir un autre type de support qui décrira la nouvelle sémantique et attendre que le ou les clients intègrent les nouvelles modifications du type de support.\nBriser la sémantique de notre type de support, ou simplement lui ajouter de nouvelles fonctionnalités, aura exactement le même résultat pour le client:\nmessages non descriptifs qui nécessiteront des informations hors bande, telles que la documentation.\n4.5 L'hypertexte en tant que moteur de l'état de l'application (HATEOAS)
"},{"id":"text-28","type":"text","heading":"","plain_text":"induit simple, visible, réutilisable et pouvant être mis en cache grâce à une intégration orientée données\ninduit une évolutivité (couplage lâche) via une liaison tardive des transitions d'application","html":"induit simple, visible, réutilisable et pouvant être mis en cache grâce à une intégration orientée données\ninduit une évolutivité (couplage lâche) via une liaison tardive des transitions d'application
"},{"id":"text-29","type":"text","heading":"","plain_text":"C’est l’une des parties les plus mal comprises du modèle REST de Roy. L'idée ici est que,\nune fois que le client et le serveur sont parvenus à un consensus sur le type de support après la négociation,\nla réponse du serveur doit fournir strictement toutes les options disponibles pour le client\npour manipuler la ressource et accéder à d’autres ressources, en utilisant la sémantique définie par\nle type de média accepté.\nComme le note Roy:","html":"C’est l’une des parties les plus mal comprises du modèle REST de Roy. L'idée ici est que,\nune fois que le client et le serveur sont parvenus à un consensus sur le type de support après la négociation,\nla réponse du serveur doit fournir strictement toutes les options disponibles pour le client\npour manipuler la ressource et accéder à d’autres ressources, en utilisant la sémantique définie par\nle type de média accepté.\nComme le note Roy:
"},{"id":"text-30","type":"text","heading":"","plain_text":"Une API REST doit être entrée sans connaissance préalable au-delà de l'URI initial (signet).\net un ensemble de types de supports standardisés adaptés au public cible\n(c’est-à-dire qu’il devrait être compris par tout client susceptible d’utiliser l’API).\nÀ partir de ce moment, toutes les transitions d'état de l'application doivent être pilotées par le client\nsélection des choix fournis par le serveur présents dans les représentations reçues\nou implicite par la manipulation de ces représentations par l'utilisateur.\nLes transitions peuvent être déterminées (ou limitées par) la connaissance du client des médias\ntypes et mécanismes de communication des ressources, qui peuvent tous deux être améliorés\nà la volée (par exemple, code à la demande).\n– Roy Fielding","html":"Une API REST doit être entrée sans connaissance préalable au-delà de l'URI initial (signet).\net un ensemble de types de supports standardisés adaptés au public cible\n(c’est-à-dire qu’il devrait être compris par tout client susceptible d’utiliser l’API).\nÀ partir de ce moment, toutes les transitions d'état de l'application doivent être pilotées par le client\nsélection des choix fournis par le serveur présents dans les représentations reçues\nou implicite par la manipulation de ces représentations par l'utilisateur.\nLes transitions peuvent être déterminées (ou limitées par) la connaissance du client des médias\ntypes et mécanismes de communication des ressources, qui peuvent tous deux être améliorés\nà la volée (par exemple, code à la demande).\n– Roy Fielding
"},{"id":"text-31","type":"text","heading":"","plain_text":"cependant, L’une des conditions à remplir pour qu'HATEOAS fonctionne est que le type de média lui-même doit permettre\nà son vocabulaire hypermédia.\nPar exemple, avec application / json Type de support cela ne fonctionnerait pas comme JSON lui-même\n(application / json Le type de support n’est rien de plus qu’un JSON) ne fournit aucun de ces mécanismes.\nAu lieu de cela, le serveur et le client doivent s’accorder sur un format offrant de tels mécanismes.\nMalheureusement, la pratique courante est de mettre application / json dans notre en-tête Content-Type indiquant\nque le type de réponse suit ce type de média, puis à l'intérieur de la réponse, nous ajoutons\nsémantique concernant l'hypermédia. Ensuite, nous transmettons des informations hors bande au client,\ncomme la documentation, et exiger de les vérifier avant d'identifier l'analyse et l'utilisation de l'hypermédia\nsémantique de notre API.\n5. Clients et applications API\n5.1. Responsabilités du client et de l'application\nLes responsabilités du client et de l'application sont parfois mélangées.\nUn client est responsable de la compréhension, de l’interaction avec l’API et de la manipulation des ressources de l’API, en fonction de la sémantique du type de support.\net runtime HATEOAS. Le client est responsable de la fourniture dans l’application de la liste des ressources disponibles dans l’API,\nleurs champs, leurs capacités, les actions disponibles et tout hypermédia disponible.\nLa responsabilité de l'application, d'autre part, ne doit pas inclure les détails spécifiques à l'API.\nAu lieu de cela, en utilisant le client, il devrait extraire tout ce dont le domaine d’application a besoin, dans les limites des capacités de l’API.\nPensez aux appareils téléphoniques résidentiels traditionnels.\nLe fil téléphonique et ses signaux constituent l’API.\nLe périphérique utilisé pour coder / décoder les signaux de fil est le client API.\nSur un appareil, nous pouvons exécuter notre application.\nLe PSTN, le RNIS, le (A) DSL, etc. sont tous différents types de média pour la même API (signaux filaires).\nPour chacun d'eux, nous avons besoin d'un client (périphérique / modem) capable de comprendre (coder / décoder) les signaux de fil de ce type de support.\nEn utilisant ce client, nous pouvons créer n’importe quel type d’application, dans l’espace réalisable du type de support.\nL’application ne traite pas de la sémantique de l’API, mais utilise le client pour effectuer ses tâches.\n5.2. Le principe du facteur humain\nIl existe deux types d’intervention humaine lors de la création d’un client API:","html":"cependant, L’une des conditions à remplir pour qu'HATEOAS fonctionne est que le type de média lui-même doit permettre\nà son vocabulaire hypermédia.\nPar exemple, avec application / json Type de support cela ne fonctionnerait pas comme JSON lui-même\n(application / json Le type de support n’est rien de plus qu’un JSON) ne fournit aucun de ces mécanismes.\nAu lieu de cela, le serveur et le client doivent s’accorder sur un format offrant de tels mécanismes.\nMalheureusement, la pratique courante est de mettre application / json dans notre en-tête Content-Type indiquant\nque le type de réponse suit ce type de média, puis à l'intérieur de la réponse, nous ajoutons\nsémantique concernant l'hypermédia. Ensuite, nous transmettons des informations hors bande au client,\ncomme la documentation, et exiger de les vérifier avant d'identifier l'analyse et l'utilisation de l'hypermédia\nsémantique de notre API.\n5. Clients et applications API\n5.1. Responsabilités du client et de l'application\nLes responsabilités du client et de l'application sont parfois mélangées.\nUn client est responsable de la compréhension, de l’interaction avec l’API et de la manipulation des ressources de l’API, en fonction de la sémantique du type de support.\net runtime HATEOAS. Le client est responsable de la fourniture dans l’application de la liste des ressources disponibles dans l’API,\nleurs champs, leurs capacités, les actions disponibles et tout hypermédia disponible.\nLa responsabilité de l'application, d'autre part, ne doit pas inclure les détails spécifiques à l'API.\nAu lieu de cela, en utilisant le client, il devrait extraire tout ce dont le domaine d’application a besoin, dans les limites des capacités de l’API.\nPensez aux appareils téléphoniques résidentiels traditionnels.\nLe fil téléphonique et ses signaux constituent l’API.\nLe périphérique utilisé pour coder / décoder les signaux de fil est le client API.\nSur un appareil, nous pouvons exécuter notre application.\nLe PSTN, le RNIS, le (A) DSL, etc. sont tous différents types de média pour la même API (signaux filaires).\nPour chacun d'eux, nous avons besoin d'un client (périphérique / modem) capable de comprendre (coder / décoder) les signaux de fil de ce type de support.\nEn utilisant ce client, nous pouvons créer n’importe quel type d’application, dans l’espace réalisable du type de support.\nL’application ne traite pas de la sémantique de l’API, mais utilise le client pour effectuer ses tâches.\n5.2. Le principe du facteur humain\nIl existe deux types d’intervention humaine lors de la création d’un client API:
"},{"id":"text-32","type":"text","heading":"","plain_text":"1 fois: Programmer le client une seule fois pour comprendre correctement le type de support et laisser le\nle travail client pour toute API qui suit ce type de support même lorsque les API évoluent, étant donné qu'il est conforme aux spécifications de type de support.\nLa seule chose dont le client a besoin est l'URI initial de l'API.\nmulti-pli: Programmer le client une fois pour comprendre le type de média.\nModifiez ensuite le client pour analyser et comprendre correctement l’API à l’aide d’un contrat hors connexion.\n(documentation sur les ressources disponibles, les champs, la pagination, etc.), puis\nchaque fois que l'API évolue (par exemple, l'ajout d'une ressource ou d'un champ), reprogrammez le client en conséquence. L'étendue de l'implication humaine\npendant cette phase dépend de la faiblesse du type de média.","html":"1 fois: Programmer le client une seule fois pour comprendre correctement le type de support et laisser le\nle travail client pour toute API qui suit ce type de support même lorsque les API évoluent, étant donné qu'il est conforme aux spécifications de type de support.\nLa seule chose dont le client a besoin est l'URI initial de l'API.\nmulti-pli: Programmer le client une fois pour comprendre le type de média.\nModifiez ensuite le client pour analyser et comprendre correctement l’API à l’aide d’un contrat hors connexion.\n(documentation sur les ressources disponibles, les champs, la pagination, etc.), puis\nchaque fois que l'API évolue (par exemple, l'ajout d'une ressource ou d'un champ), reprogrammez le client en conséquence. L'étendue de l'implication humaine\npendant cette phase dépend de la faiblesse du type de média.
"},{"id":"text-33","type":"text","heading":"","plain_text":"Une API qui suit le modèle REST devrait être évolutive sans qu'il soit nécessaire\nd’implication humaine du côté client, étant donné que le client comprend le type de média.\nL’un des effets secondaires d’une telle évolutivité et d’un seul client est que la la gestion des versions ne doit pas avoir lieu dans l'URL mais dans le type de support lui-même.","html":"Une API qui suit le modèle REST devrait être évolutive sans qu'il soit nécessaire\nd’implication humaine du côté client, étant donné que le client comprend le type de média.\nL’un des effets secondaires d’une telle évolutivité et d’un seul client est que la la gestion des versions ne doit pas avoir lieu dans l'URL mais dans le type de support lui-même.
"},{"id":"text-34","type":"text","heading":"","plain_text":"La gestion des versions d'une interface n'est qu'un moyen poli de tuer les applications déployées\nLa raison pour créer une véritable API REST est d'obtenir une capacité d'évolution… un «v1» est un moyen majeur pour vos clients d'API, indiquant RPC / HTTP (pas REST).\nRoy Fielding","html":"La gestion des versions d'une interface n'est qu'un moyen poli de tuer les applications déployées\nLa raison pour créer une véritable API REST est d'obtenir une capacité d'évolution… un «v1» est un moyen majeur pour vos clients d'API, indiquant RPC / HTTP (pas REST).\nRoy Fielding
"},{"id":"text-35","type":"text","heading":"","plain_text":"6. REST appliqué dans une API moderne\nLors de l'ingénierie d'une API REST, il existe 2 approches:","html":"6. REST appliqué dans une API moderne\nLors de l'ingénierie d'une API REST, il existe 2 approches:
"},{"id":"text-36","type":"text","heading":"","plain_text":"concevoir une API spécialisée, généralement pilotée par l'interface utilisateur: les ressources et leur facilité de navigation sont étroitement associées à l'application spécifique conçue pour\nconcevoir une API générique, généralement pilotée par les données: les ressources sont plus génériques et les fonctionnalités de l’API permettent une multitude de transformations.","html":"concevoir une API spécialisée, généralement pilotée par l'interface utilisateur: les ressources et leur facilité de navigation sont étroitement associées à l'application spécifique conçue pour\nconcevoir une API générique, généralement pilotée par les données: les ressources sont plus génériques et les fonctionnalités de l’API permettent une multitude de transformations.
"},{"id":"text-37","type":"text","heading":"","plain_text":"Les API spécialisées pourraient être plus efficaces ou présenter des caractéristiques avantageuses cruciales pour le domaine, conçues pour\ncar ils ne sont optimisés que pour ce cas particulier.\nCependant, ils posent des problèmes lorsqu'ils doivent être réutilisés par toute autre application ne partageant pas la même interface utilisateur.\nEn conséquence, ces API sont très spéciales et un peu rares.\nD'autre part, les API pilotées par les données sont plus génériques et facilitent toute application pour demander les données optimisées.\n(dans le cadre des capacités de l’API) pour son cas d’utilisation.\nPouvoir spécifier les besoins de notre application lors de la demande de données à partir d’une API est crucial,\nsurtout si notre activité dépend de la capacité d’adoption de notre API.\nPour les sous-sections suivantes, nous nous concentrerons principalement sur les API de données génériques,\nCependant, la plupart des choses mentionnées ici peuvent également être appliquées dans une API spécialisée ou pilotée par une interface utilisateur.\n6.1. Exigences d'une API REST moderne\nLe modèle REST est conçu pour la communication de machine à machine de tout type.\nCependant, comme cette forme de communication devient de plus en plus courante,\nles clients attendent plus d'options (capacités) de la part du serveur pour leurs réponses.\nIl ne suffit pas de demander et d’obtenir la ressource, mais nous devrions pouvoir spécifier\nau serveur quelles transformations devraient s'appliquer, selon nos besoins.\nDe nos jours, nous utilisons tellement les API en réseau que nous devons essentiellement\nfournir un ORM au client via HTTP (ou tout autre protocole).\nNous fournissons ici une liste de fonctionnalités (nous les appelons capacités) qui, selon nous, devraient être intégrées à une API réseau moderne,\nen 2017.\n6.1.1. Champs clairsemés (collection / ressource)\nLe client doit pouvoir demander et obtenir des attributs spécifiques (c'est-à-dire un sous-ensemble) de la représentation des ressources.\nÉgalement liée, il convient de noter qu’une représentation d’une ressource pourrait avoir un ensemble de\nattributs pour différents clients, généralement en fonction des autorisations du client ou du rôle utilisateur qu’il représente.\n6.1.2. Associations à la demande (collection / ressource)\nLe client doit pouvoir demander aux associations associées à la ressource initiale principale, dans la même demande.\nCe qui différencie une association d’un attribut est que le premier a\nune identification dédiée. De plus, si l’API expose l’association en tant que ressource dédiée,\nl'identifiant peut être utilisé comme identification.\nLe client doit pouvoir trier en fonction d'un ou de plusieurs attributs et paginer la collection.\nbasé sur la page, la taille de la page et éventuellement un décalage.\n6.1.4. Filtrage des collections (collection uniquement)\nLe client doit pouvoir exécuter n’importe quel type de filtrage de collection, tant qu’il ne pose pas\ntoute menace à la sécurité ou ralentit les performances de l'API.\n6.1.5. Requêtes d'agrégation (collection uniquement)\nLe client doit pouvoir exécuter n’importe quelle requête d’agrégation, tant que cela ne pose pas\ntoute menace à la sécurité ou ralentit les performances de l'API.\n6.1.6. Types de données !\nLe client doit connaître les types de données des attributs de la représentation demandée d'une ressource.\nLes formats de message fournissent certains types de données mais ils sont plutôt basiques.\nPar exemple, JSON définit Chaîne, Booléen, Nombre, Tableau, et nul.\nRien de plus que cela, nous devons le définir dans les documentations.\nNous pensons que ces 5 types de données fournis par JSON ne sont qu’une blague pour les API modernes et que nous devrions\navoir une liste beaucoup plus grande d'options à sélectionner.\nEn outre, nous devrions pouvoir fournir des types personnalisés de manière simple. Par exemple, un champ est Chaîne mais\na une longueur maximale de 255 caractères, il suit une expression rationnelle spécifique, etc.\n6.1.7 Twist complot: cette liste est sans fin\nBien que nous sentions que aujourd'hui ces capacités devraient exister dans toute API moderne, Cette liste n'est pas exclusive.\nEn fait, il pourrait y avoir des capacités à l’avenir qui pourraient ne pas sembler nécessaires aujourd’hui.\nPar exemple, joignant une ou plusieurs ressources, d’autres opérations inspirées de la base de données appliquées aux ressources,\ninternationalisation et localisation des données, serveur HTTP / 2 Push sur certaines requêtes, livraison d'événements génériques à l'aide de HTTP Push sur d'autres\nressources sur des états spécifiques et d’autres capacités que nous n’avons même pas imaginées.\nDans tout les cas, ces capacités doivent être transparentes et auto-descriptives pour le client, sans aucune documentation ni implication humaine, autre\nque de programmer le client pour prendre en charge le ou les types de média et de le pointer vers l’URI d’API initial.\n6.2. Types de média vs HATEOAS\nMaintenant, le lecteur pourrait se demander: où est le lieu approprié pour décrire ces capacités,\ndans le type de support de notre API ou en utilisant HATEOAS?\nQu'est-ce qui va où?\n6.2.1. Définir un nouveau type de support n'est pas facile et doit être évité\nLa création d'un nouveau type de support pour notre API est généralement considérée comme une mauvaise pratique.\nCréez un nouveau type de support uniquement si vous êtes certain qu'aucun des éléments déjà publiés\nLes types de supports peuvent s'intégrer dans la conception de votre API.\nEn outre, étendre un type de média existant ou ajouter un type de média complémentaire à un\nexistant (comme application / vnd.api + json + my_custom_data_types) ne fonctionnerait pas.\nNon seulement la spécification de type de support existante ne fournit aucun principe d'extensibilité,\nmais aussi, la raison principale est que le client doit comprendre le type de média avant de commencer.\nPar conséquent, si nous souhaitons utiliser certains Nouveau types personnalisés dans notre API (déjà déployée), nous devrions publier\nle type de média avant la main et laissez humains implémenter du code pour analyser complètement les réponses de l'API qui\nsuivez ce type de support ou les réponses de l'API que leur type de support inclut également ce nouveau type de support.\n6.2.2. HATEOAS peut devenir assez lourd\nImaginez si nous devons décrire dans une ressource toutes les actions disponibles ainsi que l'API disponible\ncapacités dans cette ressource spécifique.\nLa réponse de notre API exploserait simplement en termes de taille tout en rendant notre API super complexe.\n6.2.3. Équilibrage entre types de média et HATEOAS\nL’idée est que les types de média décrivent les capacités génériques alors que HATEOAS\ndécrire les capacités spécifiques aux ressources.\nCependant, nous devrions noter que Les types de média ne sont pas analysés par le client (il n'y a jamais eu une telle intention de toute façon)\nce qui signifie que le client doit être préalablement programmé par un humain afin de prendre en charge ce type de support.\nPar conséquent, le type de support ne peut pas être très restrictif, car cela limiterait la liberté du concepteur d’API.\npour concevoir l’API comme elle le souhaite.\nPar exemple, pour la pagination, la plupart des API RESTy utilisent un page et un par page paramètre dans l'URL.\nSi le type de support décrit comment paginer en utilisant, par exemple, un modèle d’URL sur le chemin de la ressource (comme / ressource? page = page & per_page = per_page & offset = offset)\ncela voudrait dire que tout Les API qui suivent ce type de support doivent avoir la pagination qui suit ce modèle d’URL.\nLe niveau de restriction devient plus évident lors de la description de capacités plus complexes.\nEn revanche, si tout le monde suit ce type de média, il est plus facile de programmer nos clients.\nPlus précisément, en particulier lorsque le type de support est restrictif, si nous créons un client qui analyse les réponses à l’aide de ce type de support.\nEnsuite, il est facile de la "configurer" pour une autre API qui suit également le même type de média.\nHATEOAS devrait essentiellement complément type de média en fournissant la sémantique définie par le type de média hypermédia dans runtime\npour que le client fonctionne correctement.\nPar exemple, HATEOAS pourrait décrire, ressource par ressource, si la pagination est prise en charge, quel est le maximum par page etc.\n6.2.4. Une architecture alternative\nNous pensons que la spécification et l'utilisation actuelles du type de média sont obsolètes.\nSi le génie logiciel nous a appris quelque chose, c'est que la composition peut appliquer le principe de responsabilité unique, si elle est utilisée correctement.\nInspirés par cela, nous proposerons ultérieurement un nouveau concept: les MicroTypes, de petits modules réutilisables combinés ensemble, peuvent former un type de support.\nEn conséquence, les clients devraient pouvoir même négocier des parties du type de support et non le type de support dans son ensemble.\nDe plus, au lieu de mélanger les données avec HATEOAS dans les réponses de l'API, nous introduirons l'introspection de nos ressources.\n7. Spécifications de l'API aujourd'hui\nMaintenant que nous avons défini ce que REST est, selon Roy, quelles fonctionnalités les API modernes devraient prendre en charge et où\nils devraient leur fournir,\nvoyons les spécifications des API REST (y) disponibles à compter d’aujourd’hui, septembre 2017, ce qu’elles fournissent et comment\nceux-ci suivent de près le modèle REST.\n7.1. Notre cas d'utilisation\nNotre cas d'utilisation est une miniature d'une autre application sociale.\nPlus précisément, dans notre domaine API, nous avons un Utilisateur ressource qui a d'autres ressources associées, comme Micropost, Comme, etc\nPour notre format de message, nous utiliserons JSON car c’est le plus populaire, mais il pourrait s’agir de XML, YAML, etc.","html":"Les API spécialisées pourraient être plus efficaces ou présenter des caractéristiques avantageuses cruciales pour le domaine, conçues pour\ncar ils ne sont optimisés que pour ce cas particulier.\nCependant, ils posent des problèmes lorsqu'ils doivent être réutilisés par toute autre application ne partageant pas la même interface utilisateur.\nEn conséquence, ces API sont très spéciales et un peu rares.\nD'autre part, les API pilotées par les données sont plus génériques et facilitent toute application pour demander les données optimisées.\n(dans le cadre des capacités de l’API) pour son cas d’utilisation.\nPouvoir spécifier les besoins de notre application lors de la demande de données à partir d’une API est crucial,\nsurtout si notre activité dépend de la capacité d’adoption de notre API.\nPour les sous-sections suivantes, nous nous concentrerons principalement sur les API de données génériques,\nCependant, la plupart des choses mentionnées ici peuvent également être appliquées dans une API spécialisée ou pilotée par une interface utilisateur.\n6.1. Exigences d'une API REST moderne\nLe modèle REST est conçu pour la communication de machine à machine de tout type.\nCependant, comme cette forme de communication devient de plus en plus courante,\nles clients attendent plus d'options (capacités) de la part du serveur pour leurs réponses.\nIl ne suffit pas de demander et d’obtenir la ressource, mais nous devrions pouvoir spécifier\nau serveur quelles transformations devraient s'appliquer, selon nos besoins.\nDe nos jours, nous utilisons tellement les API en réseau que nous devons essentiellement\nfournir un ORM au client via HTTP (ou tout autre protocole).\nNous fournissons ici une liste de fonctionnalités (nous les appelons capacités) qui, selon nous, devraient être intégrées à une API réseau moderne,\nen 2017.\n6.1.1. Champs clairsemés (collection / ressource)\nLe client doit pouvoir demander et obtenir des attributs spécifiques (c'est-à-dire un sous-ensemble) de la représentation des ressources.\nÉgalement liée, il convient de noter qu’une représentation d’une ressource pourrait avoir un ensemble de\nattributs pour différents clients, généralement en fonction des autorisations du client ou du rôle utilisateur qu’il représente.\n6.1.2. Associations à la demande (collection / ressource)\nLe client doit pouvoir demander aux associations associées à la ressource initiale principale, dans la même demande.\nCe qui différencie une association d’un attribut est que le premier a\nune identification dédiée. De plus, si l’API expose l’association en tant que ressource dédiée,\nl'identifiant peut être utilisé comme identification.\nLe client doit pouvoir trier en fonction d'un ou de plusieurs attributs et paginer la collection.\nbasé sur la page, la taille de la page et éventuellement un décalage.\n6.1.4. Filtrage des collections (collection uniquement)\nLe client doit pouvoir exécuter n’importe quel type de filtrage de collection, tant qu’il ne pose pas\ntoute menace à la sécurité ou ralentit les performances de l'API.\n6.1.5. Requêtes d'agrégation (collection uniquement)\nLe client doit pouvoir exécuter n’importe quelle requête d’agrégation, tant que cela ne pose pas\ntoute menace à la sécurité ou ralentit les performances de l'API.\n6.1.6. Types de données !\nLe client doit connaître les types de données des attributs de la représentation demandée d'une ressource.\nLes formats de message fournissent certains types de données mais ils sont plutôt basiques.\nPar exemple, JSON définit Chaîne, Booléen, Nombre, Tableau, et nul.\nRien de plus que cela, nous devons le définir dans les documentations.\nNous pensons que ces 5 types de données fournis par JSON ne sont qu’une blague pour les API modernes et que nous devrions\navoir une liste beaucoup plus grande d'options à sélectionner.\nEn outre, nous devrions pouvoir fournir des types personnalisés de manière simple. Par exemple, un champ est Chaîne mais\na une longueur maximale de 255 caractères, il suit une expression rationnelle spécifique, etc.\n6.1.7 Twist complot: cette liste est sans fin\nBien que nous sentions que aujourd'hui ces capacités devraient exister dans toute API moderne, Cette liste n'est pas exclusive.\nEn fait, il pourrait y avoir des capacités à l’avenir qui pourraient ne pas sembler nécessaires aujourd’hui.\nPar exemple, joignant une ou plusieurs ressources, d’autres opérations inspirées de la base de données appliquées aux ressources,\ninternationalisation et localisation des données, serveur HTTP / 2 Push sur certaines requêtes, livraison d'événements génériques à l'aide de HTTP Push sur d'autres\nressources sur des états spécifiques et d’autres capacités que nous n’avons même pas imaginées.\nDans tout les cas, ces capacités doivent être transparentes et auto-descriptives pour le client, sans aucune documentation ni implication humaine, autre\nque de programmer le client pour prendre en charge le ou les types de média et de le pointer vers l’URI d’API initial.\n6.2. Types de média vs HATEOAS\nMaintenant, le lecteur pourrait se demander: où est le lieu approprié pour décrire ces capacités,\ndans le type de support de notre API ou en utilisant HATEOAS?\nQu'est-ce qui va où?\n6.2.1. Définir un nouveau type de support n'est pas facile et doit être évité\nLa création d'un nouveau type de support pour notre API est généralement considérée comme une mauvaise pratique.\nCréez un nouveau type de support uniquement si vous êtes certain qu'aucun des éléments déjà publiés\nLes types de supports peuvent s'intégrer dans la conception de votre API.\nEn outre, étendre un type de média existant ou ajouter un type de média complémentaire à un\nexistant (comme application / vnd.api + json + my_custom_data_types) ne fonctionnerait pas.\nNon seulement la spécification de type de support existante ne fournit aucun principe d'extensibilité,\nmais aussi, la raison principale est que le client doit comprendre le type de média avant de commencer.\nPar conséquent, si nous souhaitons utiliser certains Nouveau types personnalisés dans notre API (déjà déployée), nous devrions publier\nle type de média avant la main et laissez humains implémenter du code pour analyser complètement les réponses de l'API qui\nsuivez ce type de support ou les réponses de l'API que leur type de support inclut également ce nouveau type de support.\n6.2.2. HATEOAS peut devenir assez lourd\nImaginez si nous devons décrire dans une ressource toutes les actions disponibles ainsi que l'API disponible\ncapacités dans cette ressource spécifique.\nLa réponse de notre API exploserait simplement en termes de taille tout en rendant notre API super complexe.\n6.2.3. Équilibrage entre types de média et HATEOAS\nL’idée est que les types de média décrivent les capacités génériques alors que HATEOAS\ndécrire les capacités spécifiques aux ressources.\nCependant, nous devrions noter que Les types de média ne sont pas analysés par le client (il n'y a jamais eu une telle intention de toute façon)\nce qui signifie que le client doit être préalablement programmé par un humain afin de prendre en charge ce type de support.\nPar conséquent, le type de support ne peut pas être très restrictif, car cela limiterait la liberté du concepteur d’API.\npour concevoir l’API comme elle le souhaite.\nPar exemple, pour la pagination, la plupart des API RESTy utilisent un page et un par page paramètre dans l'URL.\nSi le type de support décrit comment paginer en utilisant, par exemple, un modèle d’URL sur le chemin de la ressource (comme / ressource? page = page & per_page = per_page & offset = offset)\ncela voudrait dire que tout Les API qui suivent ce type de support doivent avoir la pagination qui suit ce modèle d’URL.\nLe niveau de restriction devient plus évident lors de la description de capacités plus complexes.\nEn revanche, si tout le monde suit ce type de média, il est plus facile de programmer nos clients.\nPlus précisément, en particulier lorsque le type de support est restrictif, si nous créons un client qui analyse les réponses à l’aide de ce type de support.\nEnsuite, il est facile de la "configurer" pour une autre API qui suit également le même type de média.\nHATEOAS devrait essentiellement complément type de média en fournissant la sémantique définie par le type de média hypermédia dans runtime\npour que le client fonctionne correctement.\nPar exemple, HATEOAS pourrait décrire, ressource par ressource, si la pagination est prise en charge, quel est le maximum par page etc.\n6.2.4. Une architecture alternative\nNous pensons que la spécification et l'utilisation actuelles du type de média sont obsolètes.\nSi le génie logiciel nous a appris quelque chose, c'est que la composition peut appliquer le principe de responsabilité unique, si elle est utilisée correctement.\nInspirés par cela, nous proposerons ultérieurement un nouveau concept: les MicroTypes, de petits modules réutilisables combinés ensemble, peuvent former un type de support.\nEn conséquence, les clients devraient pouvoir même négocier des parties du type de support et non le type de support dans son ensemble.\nDe plus, au lieu de mélanger les données avec HATEOAS dans les réponses de l'API, nous introduirons l'introspection de nos ressources.\n7. Spécifications de l'API aujourd'hui\nMaintenant que nous avons défini ce que REST est, selon Roy, quelles fonctionnalités les API modernes devraient prendre en charge et où\nils devraient leur fournir,\nvoyons les spécifications des API REST (y) disponibles à compter d’aujourd’hui, septembre 2017, ce qu’elles fournissent et comment\nceux-ci suivent de près le modèle REST.\n7.1. Notre cas d'utilisation\nNotre cas d'utilisation est une miniature d'une autre application sociale.\nPlus précisément, dans notre domaine API, nous avons un Utilisateur ressource qui a d'autres ressources associées, comme Micropost, Comme, etc\nPour notre format de message, nous utiliserons JSON car c’est le plus populaire, mais il pourrait s’agir de XML, YAML, etc.
"},{"id":"text-38","type":"text","heading":"","plain_text":"Utilisateur","html":"Utilisateur
"},{"id":"text-39","type":"text","heading":"","plain_text":"identifiant, une chaîne, jamais vide ou NULL, ID principal de la ressource\nemail, une chaîne, jamais vide ou NULL, avec une longueur maximale de 255 caractères, format de courrier électronique\nprénom, une chaîne, avec une longueur maximale de 150 caractères\ndate de naissance, une chaîne représentant une date en fonction de iso8601, dans 2017-04-01 format.\ncréé à, une chaîne, jamais vide ou NULL, représentant un DateTime selon iso8601, en UTC\nmicroposts_count un nombre entier","html":"identifiant, une chaîne, jamais vide ou NULL, ID principal de la ressource\nemail, une chaîne, jamais vide ou NULL, avec une longueur maximale de 255 caractères, format de courrier électronique\nprénom, une chaîne, avec une longueur maximale de 150 caractères\ndate de naissance, une chaîne représentant une date en fonction de iso8601, dans 2017-04-01 format.\ncréé à, une chaîne, jamais vide ou NULL, représentant un DateTime selon iso8601, en UTC\nmicroposts_count un nombre entier
"},{"id":"text-40","type":"text","heading":"","plain_text":"Donc, étant donné ces propriétés de modèle REST nous pourrait avoir les itinéraires suivants:","html":"Donc, étant donné ces propriétés de modèle REST nous pourrait avoir les itinéraires suivants:
"},{"id":"text-41","type":"text","heading":"","plain_text":"Utilisateurs Ressource (/ api / utilisateurs):","html":"Utilisateurs Ressource (/ api / utilisateurs):
"},{"id":"text-42","type":"text","heading":"","plain_text":"Liste des utilisateurs (GET / api / utilisateurs): Obtient une collection de Utilisateur Ressources\nCréer un nouvel utilisateur (POST / api / utilisateurs): Crée un nouveau Utilisateur avec les attributs spécifiés.","html":"Liste des utilisateurs (GET / api / utilisateurs): Obtient une collection de Utilisateur Ressources\nCréer un nouvel utilisateur (POST / api / utilisateurs): Crée un nouveau Utilisateur avec les attributs spécifiés.
"},{"id":"text-43","type":"text","heading":"","plain_text":"Utilisateur Ressource (/ api / utilisateurs / id):","html":"Utilisateur Ressource (/ api / utilisateurs / id):
"},{"id":"text-44","type":"text","heading":"","plain_text":"Obtenir un utilisateur (GET / api / users / id): Obtient les attributs du spécifié Utilisateur\nMettre à jour un utilisateur PATCH / api / utilisateurs / id: Met à jour un Utilisateur avec les attributs spécifiés\nSupprimer un utilisateur DELETE / api / users / id: Supprime un Utilisateur","html":"Obtenir un utilisateur (GET / api / users / id): Obtient les attributs du spécifié Utilisateur\nMettre à jour un utilisateur PATCH / api / utilisateurs / id: Met à jour un Utilisateur avec les attributs spécifiés\nSupprimer un utilisateur DELETE / api / users / id: Supprime un Utilisateur
"},{"id":"text-45","type":"text","heading":"","plain_text":"Utilisateurs et Utilisateur sont deux ressources distinctes qui sont souvent, à tort, considérées comme une seule et même ressource.\nEn outre, le fait que Utilisateurs est une collection de Utilisateur les objets, c’est parce que cela répond à nos besoins, mais il n’a pas nécessairement\nêtre comme ça.\nComme nous l'avons mentionné, Utilisateur la ressource a aussi des associations (ou des relations / relations si vous préférez),\ncomme Micropostes.\n7.1.1. Ressource utilisateur\nEn langage JSON simple, la ressource utilisateur devrait ressembler à ceci:","html":"Utilisateurs et Utilisateur sont deux ressources distinctes qui sont souvent, à tort, considérées comme une seule et même ressource.\nEn outre, le fait que Utilisateurs est une collection de Utilisateur les objets, c’est parce que cela répond à nos besoins, mais il n’a pas nécessairement\nêtre comme ça.\nComme nous l'avons mentionné, Utilisateur la ressource a aussi des associations (ou des relations / relations si vous préférez),\ncomme Micropostes.\n7.1.1. Ressource utilisateur\nEn langage JSON simple, la ressource utilisateur devrait ressembler à ceci:
"},{"id":"text-46","type":"text","heading":"","plain_text":""utilisateur": \n "id":"685",\n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance": "1988-12-12",\n "créé à": "2014-01-06T20: 46: 55Z",\n "microposts_count":50","html":""utilisateur": \n "id":"685",\n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance": "1988-12-12",\n "créé à": "2014-01-06T20: 46: 55Z",\n "microposts_count":50
"},{"id":"text-47","type":"text","heading":"","plain_text":"7.1.2. Ressource utilisateurs (une collection de ressources utilisateur)\nUne collection de Utilisateur les ressources, les Utilisateurs ressource, ressemblerait à:","html":"7.1.2. Ressource utilisateurs (une collection de ressources utilisateur)\nUne collection de Utilisateur les ressources, les Utilisateurs ressource, ressemblerait à:
"},{"id":"text-48","type":"text","heading":"","plain_text":"{\n "utilisateurs": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance": "1988-12-12",\n "créé à": "2014-01-06T20: 46: 55Z",\n "microposts_count":50\n , \n "id":"9124",\n "email": "[email protected]",\n "prénom": "Robert Clarsson",\n "date de naissance": "1940-11-10",\n "créé à": "2016-10-06T16: 01: 24Z",\n "microposts-count": 17,\n ]","html":"{\n "utilisateurs": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance": "1988-12-12",\n "créé à": "2014-01-06T20: 46: 55Z",\n "microposts_count":50\n , \n "id":"9124",\n "email": "[email protected]",\n "prénom": "Robert Clarsson",\n "date de naissance": "1940-11-10",\n "créé à": "2016-10-06T16: 01: 24Z",\n "microposts-count": 17,\n ]
"},{"id":"text-49","type":"text","heading":"","plain_text":"Maintenant que nous avons défini la portée de notre petite API, voyons comment cela serait implémenté.\ndans les spécifications pour les API REST (y) actuellement disponibles. Nous pensons que la plupart des API actuellement déployées\nont beaucoup de similitudes avec les spécifications suivantes, à savoir la structure et la partie HATEOAS (en ce qui concerne\nliaison), et par conséquent en comparant ces spécifications avec notre modèle serait suffisant.\nNous évaluerons les spécifications pour ce qui suit:","html":"Maintenant que nous avons défini la portée de notre petite API, voyons comment cela serait implémenté.\ndans les spécifications pour les API REST (y) actuellement disponibles. Nous pensons que la plupart des API actuellement déployées\nont beaucoup de similitudes avec les spécifications suivantes, à savoir la structure et la partie HATEOAS (en ce qui concerne\nliaison), et par conséquent en comparant ces spécifications avec notre modèle serait suffisant.\nNous évaluerons les spécifications pour ce qui suit:
"},{"id":"text-50","type":"text","heading":"","plain_text":"si elles suivent le modèle REST de Roy\nsi leurs messages sont ne pas auto-descriptif, autrement dit, prendre en charge le type de média de l’API dans notre client\nnous devons également lire et comprendre la documentation pour développer notre client\nsi elles requièrent un facteur humain multiplicatif pendant que l'API évolue","html":"si elles suivent le modèle REST de Roy\nsi leurs messages sont ne pas auto-descriptif, autrement dit, prendre en charge le type de média de l’API dans notre client\nnous devons également lire et comprendre la documentation pour développer notre client\nsi elles requièrent un facteur humain multiplicatif pendant que l'API évolue
"},{"id":"text-51","type":"text","heading":"","plain_text":"7.2. JSONAPI\nJSONAPI a été créé à l'origine par Yehuda Katz, dans le cadre de la bibliothèque de données des braises d'Ember.\nDepuis lors, beaucoup de gens ont contribué et sont devenus l’un des pays les plus soutenus\nSpécifications API à partir de 2017 en termes d'outils et de bibliothèques.\n7.2.1. Ressource utilisateur","html":"7.2. JSONAPI\nJSONAPI a été créé à l'origine par Yehuda Katz, dans le cadre de la bibliothèque de données des braises d'Ember.\nDepuis lors, beaucoup de gens ont contribué et sont devenus l’un des pays les plus soutenus\nSpécifications API à partir de 2017 en termes d'outils et de bibliothèques.\n7.2.1. Ressource utilisateur
"},{"id":"text-52","type":"text","heading":"","plain_text":"{\n "Les données": \n "id":"1",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance":"1988-12-12",\n "créé à":"2014-01-06T20: 46: 55Z",\n "microposts-count":50\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 1"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 1"\n \n \n \n \n}","html":"{\n "Les données": \n "id":"1",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance":"1988-12-12",\n "créé à":"2014-01-06T20: 46: 55Z",\n "microposts-count":50\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 1"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 1"\n \n \n \n \n}
"},{"id":"text-53","type":"text","heading":"","plain_text":"7.2.2. Ressource utilisateurs (une collection de ressources utilisateur)","html":"7.2.2. Ressource utilisateurs (une collection de ressources utilisateur)
"},{"id":"text-54","type":"text","heading":"","plain_text":"{\n "Les données":[[[[\n \n "id":"1",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance":"1988-12-12",\n "créé à":"2014-01-06T20: 46: 55Z",\n "microposts-count":50\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 1"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 1"\n \n \n \n ,\n \n "id":"9124",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Robert Clarsson",\n "date de naissance":"1940-11-10",\n "créé à":"2016-10-06T16: 01: 24Z",\n "microposts-count":17\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 9124"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 9124"\n \n \n \n \n ],\n "liens": \n "soi":"/ api / users? page = 1 & per_page = 10",\n "suivant":"/ api / users? page = 2 & per_page = 10",\n "dernier":"/ api / users? page = 3 & per_page = 10"\n \n}","html":"{\n "Les données":[[[[\n \n "id":"1",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance":"1988-12-12",\n "créé à":"2014-01-06T20: 46: 55Z",\n "microposts-count":50\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 1"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 1"\n \n \n \n ,\n \n "id":"9124",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Robert Clarsson",\n "date de naissance":"1940-11-10",\n "créé à":"2016-10-06T16: 01: 24Z",\n "microposts-count":17\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 9124"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 9124"\n \n \n \n \n ],\n "liens": \n "soi":"/ api / users? page = 1 & per_page = 10",\n "suivant":"/ api / users? page = 2 & per_page = 10",\n "dernier":"/ api / users? page = 3 & per_page = 10"\n \n}
"},{"id":"text-55","type":"text","heading":"","plain_text":"7.2.3. Des reflets\nBien que la spécification fasse de gros efforts pour décrire la structure du document, nous voyons quelques\nproblèmes notables. À savoir:","html":"7.2.3. Des reflets\nBien que la spécification fasse de gros efforts pour décrire la structure du document, nous voyons quelques\nproblèmes notables. À savoir:
"},{"id":"text-56","type":"text","heading":"","plain_text":"Liens limités (pas de modèles d'URI, le client est considéré comme idiot)\nAucune action\nAucune information sur les attributs disponibles\nAucune information sur les types de données\nAucune description d'attributs","html":"Liens limités (pas de modèles d'URI, le client est considéré comme idiot)\nAucune action\nAucune information sur les attributs disponibles\nAucune information sur les types de données\nAucune description d'attributs
"},{"id":"text-57","type":"text","heading":"","plain_text":"To sum up, it doesn’t entirely follow REST model while it requires both\ndocumentation and multi-fold human factor.\n7.3. HAL\nHAL was created by Mike Kelly in 2012.\nThe key feature of HAL when it was released was the browsability/explorability of any API that adopted.\nAnother feature is the idea of curies, links inside the resource that lead to the documentation, targeted to\nhumans and not machines.\nThe resources of our use case that are presented here use JSON as a message format, but HAL is not tied to that.\n7.3.1. User resource","html":"To sum up, it doesn’t entirely follow REST model while it requires both\ndocumentation and multi-fold human factor.\n7.3. HAL\nHAL was created by Mike Kelly in 2012.\nThe key feature of HAL when it was released was the browsability/explorability of any API that adopted.\nAnother feature is the idea of curies, links inside the resource that lead to the documentation, targeted to\nhumans and not machines.\nThe resources of our use case that are presented here use JSON as a message format, but HAL is not tied to that.\n7.3.1. User resource
"},{"id":"text-58","type":"text","heading":"","plain_text":""_links": \n "self": \n "href": "/api/users/id"\n ,\n "microposts": \n "href": "/api/microposts/user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": "1",\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,","html":""_links": \n "self": \n "href": "/api/users/id"\n ,\n "microposts": \n "href": "/api/microposts/user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": "1",\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,
"},{"id":"text-59","type":"text","heading":"","plain_text":"7.3.2. Users resource (a collection of User resources)","html":"7.3.2. Users resource (a collection of User resources)
"},{"id":"text-60","type":"text","heading":"","plain_text":"{\n "_links":\n "self":\n "href":"/api/users"\n ,\n "curries":[[[[\n \n "name":"ea",\n "href":"https://example.com/docs/rels/rel",\n "templated":vrai\n \n ]\n ,\n "_embedded":{\n "users":[[[[\n \n "_links":\n "self":\n "href":"/api/users/id",\n "templated": vrai\n ,\n "microposts":\n "href":"/api/microposts?user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": 9123,\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50\n , \n "_links":\n "self":\n "href":"/api/users/id",\n "templated": vrai\n ,\n "microposts":\n "href":"/api/microposts?user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": 9123,\n "name": "Robert Clarsson",\n "email": "[email protected]",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 50,\n \n ]\n }\n}","html":"{\n "_links":\n "self":\n "href":"/api/users"\n ,\n "curries":[[[[\n \n "name":"ea",\n "href":"https://example.com/docs/rels/rel",\n "templated":vrai\n \n ]\n ,\n "_embedded":{\n "users":[[[[\n \n "_links":\n "self":\n "href":"/api/users/id",\n "templated": vrai\n ,\n "microposts":\n "href":"/api/microposts?user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": 9123,\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50\n , \n "_links":\n "self":\n "href":"/api/users/id",\n "templated": vrai\n ,\n "microposts":\n "href":"/api/microposts?user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": 9123,\n "name": "Robert Clarsson",\n "email": "[email protected]",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 50,\n \n ]\n }\n}
"},{"id":"text-61","type":"text","heading":"","plain_text":"7.3.3. Reflections\nAlthough this spec does have templated links, we see some notable issues. Namely:","html":"7.3.3. Reflections\nAlthough this spec does have templated links, we see some notable issues. Namely:
"},{"id":"text-62","type":"text","heading":"","plain_text":"No actions (they are supported by an unofficial extension)\nNo info on available attributes\nNo info on data types\nNo attributes description, requires documentation (however it does provide a link to documentation, through curries)","html":"No actions (they are supported by an unofficial extension)\nNo info on available attributes\nNo info on data types\nNo attributes description, requires documentation (however it does provide a link to documentation, through curries)
"},{"id":"text-63","type":"text","heading":"","plain_text":"To sum up, it doesn’t entirely follow REST while it requires documentation and multi-fold human factor (curies facilitate that).\n7.4. Sirène\nSiren was created by Kevin Swiber in 2012 and revolves around entités, a URI-addressable resource that has properties and actions associated with it.\nThe resources of our use case that are presented here use JSON as a message format, but Siren is not tied to that.\n7.4.1. User resource","html":"To sum up, it doesn’t entirely follow REST while it requires documentation and multi-fold human factor (curies facilitate that).\n7.4. Sirène\nSiren was created by Kevin Swiber in 2012 and revolves around entités, a URI-addressable resource that has properties and actions associated with it.\nThe resources of our use case that are presented here use JSON as a message format, but Siren is not tied to that.\n7.4.1. User resource
"},{"id":"text-64","type":"text","heading":"","plain_text":""class": [[[[ "user" ],\n "Propriétés": \n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,\n ,\n "actions": [[[[\n \n "name": "get-user",\n "Titre": "Get User",\n "method": "OBTENIR",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n ,\n \n "name": "update-user",\n "Titre": "Update User",\n "method": "PUT",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n "fields": [[[[\n "name": "name", "type": "text" ,\n ]\n ,\n \n "name": "delete-user",\n "Titre": "Get User",\n "method": "DELETE",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n \n ],\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/1" ,\n "rel":[[[["microposts"], "href":"/api/microposts?user_id=1" \n "rel":[[[["likes"], "href":"/api/likes?user_id=1" \n ]","html":""class": [[[[ "user" ],\n "Propriétés": \n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,\n ,\n "actions": [[[[\n \n "name": "get-user",\n "Titre": "Get User",\n "method": "OBTENIR",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n ,\n \n "name": "update-user",\n "Titre": "Update User",\n "method": "PUT",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n "fields": [[[[\n "name": "name", "type": "text" ,\n ]\n ,\n \n "name": "delete-user",\n "Titre": "Get User",\n "method": "DELETE",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n \n ],\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/1" ,\n "rel":[[[["microposts"], "href":"/api/microposts?user_id=1" \n "rel":[[[["likes"], "href":"/api/likes?user_id=1" \n ]
"},{"id":"text-65","type":"text","heading":"","plain_text":"7.4.2. Users resource (a collection of User resources)","html":"7.4.2. Users resource (a collection of User resources)
"},{"id":"text-66","type":"text","heading":"","plain_text":""class":[[[["users"],\n "Propriétés":nul,\n "entities":[[[[\n \n "class":[[[["user"],\n "rel":[[[["https://example.com/users/1"],\n "href":"https://example.com/users/1",\n "Propriétés":\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,\n ,\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/1" ,\n "rel":[[[["microposts"], "href":"/api/microposts?user_id=1" \n ]\n ,\n \n "class":[[[["user"],\n "rel":[[[["https://example.com/users/9124"],\n "href":"https://example.com/users/9124",\n "Propriétés":\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ,\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/9124" ,\n "rel":[[[["microposts"], "href":"https://example.com/api/microposts?user_id=9124" \n "rel":[[[["likes"], "href":"https://example.com/api/likes?user_id=9124" \n ]\n \n ],\n "actions":[[[[\n \n "name":"create-user",\n "Titre":"Create User",\n "method":"POST",\n "href":"https://example.com/users/",\n "type":"application/json",\n "fields": [[[[\n "name": "name", "type": "text" ,\n "name": "email", "type": "text" ,\n "name": "birth_date", "type": "date" ,\n ]\n \n ],\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com.api/users",\n "rel":[[[["next"], "href":"https://example.com.api/users?page=2"\n ]","html":""class":[[[["users"],\n "Propriétés":nul,\n "entities":[[[[\n \n "class":[[[["user"],\n "rel":[[[["https://example.com/users/1"],\n "href":"https://example.com/users/1",\n "Propriétés":\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,\n ,\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/1" ,\n "rel":[[[["microposts"], "href":"/api/microposts?user_id=1" \n ]\n ,\n \n "class":[[[["user"],\n "rel":[[[["https://example.com/users/9124"],\n "href":"https://example.com/users/9124",\n "Propriétés":\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ,\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/9124" ,\n "rel":[[[["microposts"], "href":"https://example.com/api/microposts?user_id=9124" \n "rel":[[[["likes"], "href":"https://example.com/api/likes?user_id=9124" \n ]\n \n ],\n "actions":[[[[\n \n "name":"create-user",\n "Titre":"Create User",\n "method":"POST",\n "href":"https://example.com/users/",\n "type":"application/json",\n "fields": [[[[\n "name": "name", "type": "text" ,\n "name": "email", "type": "text" ,\n "name": "birth_date", "type": "date" ,\n ]\n \n ],\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com.api/users",\n "rel":[[[["next"], "href":"https://example.com.api/users?page=2"\n ]
"},{"id":"text-67","type":"text","heading":"","plain_text":"7.4.3. Reflections\nThe spec takes a huge leap towards REST principles by supporting, links, actions with fields and data types, there are\nstill some issues that require human-involvement:","html":"7.4.3. Reflections\nThe spec takes a huge leap towards REST principles by supporting, links, actions with fields and data types, there are\nstill some issues that require human-involvement:
"},{"id":"text-68","type":"text","heading":"","plain_text":"No custom types for the attributes of actions\nNo info on available and required attributes\nNo info on data types on response objects\nLimited description for fields and resources","html":"No custom types for the attributes of actions\nNo info on available and required attributes\nNo info on data types on response objects\nLimited description for fields and resources
"},{"id":"text-69","type":"text","heading":"","plain_text":"To sum up, Siren is very close to a self-described REST API but in practice it requires documentation and multi-fold human factor.\n8. Ideal REST API\nHow many years these specs could sustain in terms of evolvability ? Are they built with a lifespan of 2-3 years or are they\nbuilt with a life span of 50 years?\n8.1. Capabilities of an Ideal REST API\nIn an ideal REST API, the client should be able to have all the necessary information for both\nthe request and response.","html":"To sum up, Siren is very close to a self-described REST API but in practice it requires documentation and multi-fold human factor.\n8. Ideal REST API\nHow many years these specs could sustain in terms of evolvability ? Are they built with a lifespan of 2-3 years or are they\nbuilt with a life span of 50 years?\n8.1. Capabilities of an Ideal REST API\nIn an ideal REST API, the client should be able to have all the necessary information for both\nthe request and response.
"},{"id":"text-70","type":"text","heading":"","plain_text":"About each resource returned from the API to the client:","html":"About each resource returned from the API to the client:
"},{"id":"text-71","type":"text","heading":"","plain_text":"default attributes and available (superset of default) attributes of the resource, based on the user’s permissions\ndata types for each attribute in the resource or any embedded association\nSorting/pagination, filtering and aggregation queries availability\ndata type of each attribute\ndefault embedded associations and available associations to embed","html":"default attributes and available (superset of default) attributes of the resource, based on the user’s permissions\ndata types for each attribute in the resource or any embedded association\nSorting/pagination, filtering and aggregation queries availability\ndata type of each attribute\ndefault embedded associations and available associations to embed
"},{"id":"text-72","type":"text","heading":"","plain_text":"recursively apply the same information for each association available for embedding","html":"recursively apply the same information for each association available for embedding
"},{"id":"text-73","type":"text","heading":"","plain_text":"any other capability (HTTP/2 Server Push, event delivery etc)","html":"any other capability (HTTP/2 Server Push, event delivery etc)
"},{"id":"text-74","type":"text","heading":"","plain_text":"About each resource sent to the API from the client","html":"About each resource sent to the API from the client
"},{"id":"text-75","type":"text","heading":"","plain_text":"available actions on the resource\nattributes, per action, the client can modify, based on the user’s permissions\nrequired attributes of a resource (attributes a resource doit before sending it over)\ndata types of the attributes (could be different from the resource found in the response)\nassociations that are required or can be embedded to the initial request","html":"available actions on the resource\nattributes, per action, the client can modify, based on the user’s permissions\nrequired attributes of a resource (attributes a resource doit before sending it over)\ndata types of the attributes (could be different from the resource found in the response)\nassociations that are required or can be embedded to the initial request
"},{"id":"text-76","type":"text","heading":"","plain_text":"recursively apply the same information for each association available for embedding","html":"recursively apply the same information for each association available for embedding
"},{"id":"text-77","type":"text","heading":"","plain_text":"Bien que cette liste n'est pas exhaustive, an architecture style is timeless anyway,\nwe feel that the aforementioned capabilities ought to appear in an idealized modern REST API.\nWe should also note that the reason we don’t mention anything about the headers that are required, or, the status codes\nis because we feel that these belong to the Protocol level and not in the Application level.\nAny changes on this level imply that the API breaks the protocol.\nHowever, we are pragmatic and we understand that an API designer could want to ajouter (not change)\na status code or a header in a given request/response and as a result, ideally, this should also be possible to be described.\n8.1.1. Today’s REST is far from ideal\nNow to the reader, it should be obvious that even if we manage to offload some of the aforementioned information\nto the Media Type, we would still have a très complex, massive, response from the server that mostly includes HATEOAS\nand not actual data.\nIn our experience, such responses are very hard to implement correctly, test, be performant and even debug. Après tout,\na human will sit down and write the initial code and debugging the code by the eye is important.\nSimplicity is crucial.\nMoreover, some clients might not be interested in hypermedia and evolvability at all but only the data.\nHowever such APIs force the clients to deal with it.\nIdeally we would like to give the option to the client to decide the extend of the hypermedia that it\nwill support and follow, without taking on defaults. Some clients might want to follow 100% the HATEOAS part\nof the API (and as a result be evolvable) some other clients might want the 50%, some clients might be interested\nonly in data.\nBy outputting a whole bunch of hypermedia-related information to the clients that, after all, might never use\nthem is a bad practice.\n8.1.2. Making an API REST-compliant by downplaying its capabilities\nOne could argue that we require all APIs to support features that they shouldn’t, like resource manipulation.\nFor instance, we could have a weather API with application/vnd.weather+yaml Media Type\nthat is only supposed to provide a single attribute with its value, as Integer:\nThis API devrait be REST-compliant by not providing any API capabilities, hypermedia or actions.\nOf course, the imaginary Media Type application/vnd.weather+yaml is supposed to provide all the necessary information\nbecause otherwise the client would fail to understand things like","html":"Bien que cette liste n'est pas exhaustive, an architecture style is timeless anyway,\nwe feel that the aforementioned capabilities ought to appear in an idealized modern REST API.\nWe should also note that the reason we don’t mention anything about the headers that are required, or, the status codes\nis because we feel that these belong to the Protocol level and not in the Application level.\nAny changes on this level imply that the API breaks the protocol.\nHowever, we are pragmatic and we understand that an API designer could want to ajouter (not change)\na status code or a header in a given request/response and as a result, ideally, this should also be possible to be described.\n8.1.1. Today’s REST is far from ideal\nNow to the reader, it should be obvious that even if we manage to offload some of the aforementioned information\nto the Media Type, we would still have a très complex, massive, response from the server that mostly includes HATEOAS\nand not actual data.\nIn our experience, such responses are very hard to implement correctly, test, be performant and even debug. Après tout,\na human will sit down and write the initial code and debugging the code by the eye is important.\nSimplicity is crucial.\nMoreover, some clients might not be interested in hypermedia and evolvability at all but only the data.\nHowever such APIs force the clients to deal with it.\nIdeally we would like to give the option to the client to decide the extend of the hypermedia that it\nwill support and follow, without taking on defaults. Some clients might want to follow 100% the HATEOAS part\nof the API (and as a result be evolvable) some other clients might want the 50%, some clients might be interested\nonly in data.\nBy outputting a whole bunch of hypermedia-related information to the clients that, after all, might never use\nthem is a bad practice.\n8.1.2. Making an API REST-compliant by downplaying its capabilities\nOne could argue that we require all APIs to support features that they shouldn’t, like resource manipulation.\nFor instance, we could have a weather API with application/vnd.weather+yaml Media Type\nthat is only supposed to provide a single attribute with its value, as Integer:\nThis API devrait be REST-compliant by not providing any API capabilities, hypermedia or actions.\nOf course, the imaginary Media Type application/vnd.weather+yaml is supposed to provide all the necessary information\nbecause otherwise the client would fail to understand things like
"},{"id":"text-78","type":"text","heading":"","plain_text":"what are the attributes of the response\nwhat is the data type of the temperature value (float, double, integer, bignum etc)","html":"what are the attributes of the response\nwhat is the data type of the temperature value (float, double, integer, bignum etc)
"},{"id":"text-79","type":"text","heading":"","plain_text":"We feel that although this is true, most APIs are not as simple as that.\nMoreover such APIs can’t actually be evolved without releasing a new Media Type and breaking the existing API clients.\nThere is no way of introducing change, which essentially breaks REST’s principles.\nHowever we are pragmatic: we understand that such APIs will exist and API designers want to spend as less time as possible to build such APIs.\nIntrospected REST, an architecture that we will describe later, solves that by serving hypermedia\ninformation on side and in an incremental way without breaking the simplicity.\n8.1.3. A JSON API back in time\nA JSON-based API built around 2006 would return just data. No hypermedia, no HATEOAS, only data.\nIn our use case, User resource would look like this:","html":"We feel that although this is true, most APIs are not as simple as that.\nMoreover such APIs can’t actually be evolved without releasing a new Media Type and breaking the existing API clients.\nThere is no way of introducing change, which essentially breaks REST’s principles.\nHowever we are pragmatic: we understand that such APIs will exist and API designers want to spend as less time as possible to build such APIs.\nIntrospected REST, an architecture that we will describe later, solves that by serving hypermedia\ninformation on side and in an incremental way without breaking the simplicity.\n8.1.3. A JSON API back in time\nA JSON-based API built around 2006 would return just data. No hypermedia, no HATEOAS, only data.\nIn our use case, User resource would look like this:
"},{"id":"text-80","type":"text","heading":"","plain_text":""user": \n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50","html":""user": \n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50
"},{"id":"text-81","type":"text","heading":"","plain_text":"As simple as that.\nCompared with a HATEOAS-ed response it’s simple as hell, obvious, easy to debug and understand by a human (and a client).\nIs it possible to build an API that is simple as that, be Hypermedia driven and give the client the option to decide\nthe level and type of HATEOAS it will follow?\n8.2. Deriving the need for a new model\n8.2.1. REST is complex\nAs we described earlier, mixing data with hypermedia leads to increased complexity, for both the server and the client.\nJust compare the size of our resource’s data and the size of our resource when represented by\nSiren, a hypermedia-ed API that doesn’t even being REST-compatible by missing numerous information as described\nin its reflections.\nImagine how bloated the response would look like, if we added all the capabilities described in section 6.1.\nMoreover, the hypermedia must be tailored for the user role the client acts on behalf of.\nFor instance, a user with very basic access role might only have access to retrieving resources and not manipulating them.\nOr such role could only have access to specific capabilities of the API.\nAs a result, the hypermedia provided on the response object should reflect that by not providing hypermedia that will lead to unauthorized access.\nIn fact, such design is quite difficult to implement and test from the server side.\n8.2.2. REST enforces possibly useless information\nIn REST, even if the hypermedia are rendered by taking into account the user’s role, eventually we might send more data that the client wants.\nExactly because we don’t know in advance what the client might need, we must send all the possible hypermedia information to the client, just in case.\nThe client however could only be interested in the data, or specific hypermedia types, like links, but instead gets a fully bloated response by the server.\n8.2.3. REST sacrifices performance for evolvability\nComplex or long-lived APIs tend to have many hypermedia data (links, actions, custom metadata)\nrelated to the resource itself, its associations and related resources.\nAs a result, even if the actual data could be very small the resulted response object gets much larger in size slowing down the server rendering\nand the client receiving and parsing.\nThe performance issues become more apparent on lossy networks like mobile clients, a trend that has increased over the past decade,\nor on constrained devices and environments, like IoT.\n8.2.4. REST does not support caching of hypermedia\nIn practice, the hypermedia part of a resource rarely changes, compared to the resource’s data.\nIn REST, by design, the client can’t cache the hypermedia part of the resource, even for relatively small amount of time, because\nhypermedia is part of the resource, thus caching the hypermedia can’t be separate from caching the response itself.\n8.2.5. REST doesn’t make it easy to evolve hypermedia\nAnother issue of REST is that due to the fact that everything is mixed in together, evolving hypermedia separately from the data\ncan’t happen.\nWe understand that this is actually another feature of REST design and not an issue, treating a response object as a whole and not breaking into\ndifferent parts like hypermedia and data, however, in practice, this poses difficulties for easier evolvement and maintenance of the API.\n8.2.6. REST’s power is limited by HTTP and related protocols (SIP, CoAP etc)\nAlthough REST is not dependent on any protocol or spec, the truth is that it has dominated in HTTP.\nAs we described earlier, in protocols like HTTP, content negotiation between client and server is achieved using Media Types,\nwhich is the only mechanism to define the semantics of a response.\nGiven that composite Media Types never had real composability, and the fact that they cannot be parsed by clients,\nthere is a trade off between what should go to the Media Type and what to the actual response through\nhypermedia, as described in section 6.2.3.\nThis limits the design flexibility and evolvability.\nAs a result Media Types become big monoliths that are inflexible and limit the evolvability of the API.\n8.2.6.1. No backwards compatible with any RESTly or RESTless API\nIn a perfect world, APIs are built to be alive for many decades and clients are exploiting every little feature of the API and its Media Type.\nHowever, we are in a pragmatic world where nothing is perfect and clients are built by humans who take decisions based on their time and money.\nAlthough we firmly believe that a REST API is better than any RESTly or RESTless API, we understand that there could be cases where API designers\ndevoir initially skip hypermedia part.\nThe problem is that when REST is applied to HTTP, it doesn’t allow us to easily integrate hypermedia at a later point.\nThe reason is that, in a RESTless API, adding hypermedia at a later stage would mean that we would need a new Media Type because\notherwise it would break the current semantics.\nWe would like to see a model that embraces both architectural API styles:","html":"As simple as that.\nCompared with a HATEOAS-ed response it’s simple as hell, obvious, easy to debug and understand by a human (and a client).\nIs it possible to build an API that is simple as that, be Hypermedia driven and give the client the option to decide\nthe level and type of HATEOAS it will follow?\n8.2. Deriving the need for a new model\n8.2.1. REST is complex\nAs we described earlier, mixing data with hypermedia leads to increased complexity, for both the server and the client.\nJust compare the size of our resource’s data and the size of our resource when represented by\nSiren, a hypermedia-ed API that doesn’t even being REST-compatible by missing numerous information as described\nin its reflections.\nImagine how bloated the response would look like, if we added all the capabilities described in section 6.1.\nMoreover, the hypermedia must be tailored for the user role the client acts on behalf of.\nFor instance, a user with very basic access role might only have access to retrieving resources and not manipulating them.\nOr such role could only have access to specific capabilities of the API.\nAs a result, the hypermedia provided on the response object should reflect that by not providing hypermedia that will lead to unauthorized access.\nIn fact, such design is quite difficult to implement and test from the server side.\n8.2.2. REST enforces possibly useless information\nIn REST, even if the hypermedia are rendered by taking into account the user’s role, eventually we might send more data that the client wants.\nExactly because we don’t know in advance what the client might need, we must send all the possible hypermedia information to the client, just in case.\nThe client however could only be interested in the data, or specific hypermedia types, like links, but instead gets a fully bloated response by the server.\n8.2.3. REST sacrifices performance for evolvability\nComplex or long-lived APIs tend to have many hypermedia data (links, actions, custom metadata)\nrelated to the resource itself, its associations and related resources.\nAs a result, even if the actual data could be very small the resulted response object gets much larger in size slowing down the server rendering\nand the client receiving and parsing.\nThe performance issues become more apparent on lossy networks like mobile clients, a trend that has increased over the past decade,\nor on constrained devices and environments, like IoT.\n8.2.4. REST does not support caching of hypermedia\nIn practice, the hypermedia part of a resource rarely changes, compared to the resource’s data.\nIn REST, by design, the client can’t cache the hypermedia part of the resource, even for relatively small amount of time, because\nhypermedia is part of the resource, thus caching the hypermedia can’t be separate from caching the response itself.\n8.2.5. REST doesn’t make it easy to evolve hypermedia\nAnother issue of REST is that due to the fact that everything is mixed in together, evolving hypermedia separately from the data\ncan’t happen.\nWe understand that this is actually another feature of REST design and not an issue, treating a response object as a whole and not breaking into\ndifferent parts like hypermedia and data, however, in practice, this poses difficulties for easier evolvement and maintenance of the API.\n8.2.6. REST’s power is limited by HTTP and related protocols (SIP, CoAP etc)\nAlthough REST is not dependent on any protocol or spec, the truth is that it has dominated in HTTP.\nAs we described earlier, in protocols like HTTP, content negotiation between client and server is achieved using Media Types,\nwhich is the only mechanism to define the semantics of a response.\nGiven that composite Media Types never had real composability, and the fact that they cannot be parsed by clients,\nthere is a trade off between what should go to the Media Type and what to the actual response through\nhypermedia, as described in section 6.2.3.\nThis limits the design flexibility and evolvability.\nAs a result Media Types become big monoliths that are inflexible and limit the evolvability of the API.\n8.2.6.1. No backwards compatible with any RESTly or RESTless API\nIn a perfect world, APIs are built to be alive for many decades and clients are exploiting every little feature of the API and its Media Type.\nHowever, we are in a pragmatic world where nothing is perfect and clients are built by humans who take decisions based on their time and money.\nAlthough we firmly believe that a REST API is better than any RESTly or RESTless API, we understand that there could be cases where API designers\ndevoir initially skip hypermedia part.\nThe problem is that when REST is applied to HTTP, it doesn’t allow us to easily integrate hypermedia at a later point.\nThe reason is that, in a RESTless API, adding hypermedia at a later stage would mean that we would need a new Media Type because\notherwise it would break the current semantics.\nWe would like to see a model that embraces both architectural API styles:
"},{"id":"text-82","type":"text","heading":"","plain_text":"APIs that are built to last decades and thus, support full hypermedia from the very first day of their release\nAPIs that don’t have hypermedia (the reason is none of our business), yet it is required to add hypermedia, later, in an incremental way without\nbreaking existing clients or limiting API’s flexibility","html":"APIs that are built to last decades and thus, support full hypermedia from the very first day of their release\nAPIs that don’t have hypermedia (the reason is none of our business), yet it is required to add hypermedia, later, in an incremental way without\nbreaking existing clients or limiting API’s flexibility
"},{"id":"text-83","type":"text","heading":"","plain_text":"8.2.7.2 REST does not embrace composition\nAlthough REST does not rejects the idea of composability of different API capabilities using different specs in the same response, or composite Media Types,\nit doesn’t embrace it either.\nThe symptom of non-composability is clearly visible in protocols like HTTP where Media Types\nact as big monoliths trying to describe everything in one place.\nRFC 6906 (The ‘profile’ Link Relation Type) was created to overcome such issues\nbut as we will see later this specifications lags behind over true composability and\nproper negotiation of the different profile types from the client perspective.\nIn Introspected REST, the MicroTypes is a conceptual solution to the outdated Media Type concept\nand allows us to mix-in different concepts for different kind of metadata of a resource,\nyet have all of them on demand and separated by the actual data.\n9. Introspected REST","html":"8.2.7.2 REST does not embrace composition\nAlthough REST does not rejects the idea of composability of different API capabilities using different specs in the same response, or composite Media Types,\nit doesn’t embrace it either.\nThe symptom of non-composability is clearly visible in protocols like HTTP where Media Types\nact as big monoliths trying to describe everything in one place.\nRFC 6906 (The ‘profile’ Link Relation Type) was created to overcome such issues\nbut as we will see later this specifications lags behind over true composability and\nproper negotiation of the different profile types from the client perspective.\nIn Introspected REST, the MicroTypes is a conceptual solution to the outdated Media Type concept\nand allows us to mix-in different concepts for different kind of metadata of a resource,\nyet have all of them on demand and separated by the actual data.\n9. Introspected REST
"},{"id":"text-84","type":"text","heading":"","plain_text":"Simple things should be simple and complex things should be possible.\n— Alan Kay","html":"Simple things should be simple and complex things should be possible.\n— Alan Kay
"},{"id":"text-85","type":"text","heading":"","plain_text":"In the following section we will describe our new architectural style based on a model for Networked APIs that goes beyond REST.\nThe model itself steps on Roy’s initial REST model but with the difference that instead of providing resource hypermedia at\nruntime, it provides them on the side, only if requested.\nHence, by keeping the interface uniforme the derived 3 out of 4 REST constraints that Roy defined still exist in this model:\nidentification of resources; manipulation of resources through representations et self-descriptive messages.\nHowever, instead of having the constraint of hypermédia en tant que moteur de l'état de l'application (HATEOAS), we have\nintrospection as the engine of application state (IATEOAS).\nMoreover, the introspection process can provide other kind of information, apart from hypermedia and links, that\ncan facilitate the client to take decisions on how to proceed with the application’s requests.\nTo achieve this, composition of different specs is a vital part of our model and for that we will use a new concept,\nMicroTypes, small reusable modules that a final Media Type can be composed of.\nBefore moving on, we will give concise definitions over hypermedia and metadata and break it down to different kinds of classes,\naccording to Introspected REST model.\nThese terms can overlap in the REST, however we feel that each one has its own place in our model that embraces composability.\n9.1. Data, metadata and hypermedia\n9.1.1. Les données\nData is the main variables of a resource, at a given state, at a given time.\nData is very volatile compared to other parts of a response.\n9.1.2. Hypermedia\nOriginally the hypermedia term was mostly used for linked data, in the sense of hyperlinks.\nIn REST, eventually, it also includes information for interaction and resource manipulation.\nHypermedia can be dynamic or static but regardless they are not considered part of the response data, because they define\nways to interact with the data.\nHypermedia is a very broad term and needs to be broken down in different parts.\nAlthough there isn’t any clear definition or consensus in the literature and the community, we will try to provide definitions and descriptions for\nall the different types of Hypermedia, according to our model’s perception.\n9.1.2.1. Liens\nThe most basic class of hypermedia, basically URIs that can be used to provide linking between related resources to the primary resource.\nThe properties of a link, like placement inside the response, strictly follow the semantics of the Media Type agreed.\n9.1.2.2. actes\nActions are links along with information for manipulating a resource.\nAlthough CRUD are the most popular actions of a resource, the beauty with REST, and consequently with Introspected REST,\nis that actions can go beyond plain CRUD.\nIn fact, we can define any type of action or meta-action of our internal resource, through the representation that we expose.\nAs a result, actions of a resource could be quite complex or simplistic depending on the needs and decisions of the API designer.\nActions should also describe any relevant information for the client to perform it, unless the Media Type itself describe those details.\n9.1.2.3. Forms\nAnother way of describing the manipulation options of a resource is the notion of forms.\nThe difference between actions and forms is that the latter are strictly semantically equivalent to an HTML form,\nfor the client to render.\n9.1.3. Metadata\nIf hypermedia is links and actions, then what is metadata ?\nMetadata are information about the resource that is not related with the data, including hypermedia.\nIn essence, metadata is a superset of hypermedia and it’s crucial for the client\nto understand API’s responses, access the API’s capabilities and manipulate the resources.\nMetadata could be API-specific, resource-specific, action-specific or even object-specific.\nThere could also be different kinds of metadata: runtime (i.e. pagination information), structural (i.e. data types of a resource object),\nhypermedia (i.e. links, actions, forms), informational targeted to humans (i.e. general information, descriptions), etc.\nUsually metadata is much less volatile than data, if not static, except runtime metadata\nthat depend on the request and the resource at the given time and state respectively.\n9.2. MicroTypes: reusable modules composing a Media Type","html":"In the following section we will describe our new architectural style based on a model for Networked APIs that goes beyond REST.\nThe model itself steps on Roy’s initial REST model but with the difference that instead of providing resource hypermedia at\nruntime, it provides them on the side, only if requested.\nHence, by keeping the interface uniforme the derived 3 out of 4 REST constraints that Roy defined still exist in this model:\nidentification of resources; manipulation of resources through representations et self-descriptive messages.\nHowever, instead of having the constraint of hypermédia en tant que moteur de l'état de l'application (HATEOAS), we have\nintrospection as the engine of application state (IATEOAS).\nMoreover, the introspection process can provide other kind of information, apart from hypermedia and links, that\ncan facilitate the client to take decisions on how to proceed with the application’s requests.\nTo achieve this, composition of different specs is a vital part of our model and for that we will use a new concept,\nMicroTypes, small reusable modules that a final Media Type can be composed of.\nBefore moving on, we will give concise definitions over hypermedia and metadata and break it down to different kinds of classes,\naccording to Introspected REST model.\nThese terms can overlap in the REST, however we feel that each one has its own place in our model that embraces composability.\n9.1. Data, metadata and hypermedia\n9.1.1. Les données\nData is the main variables of a resource, at a given state, at a given time.\nData is very volatile compared to other parts of a response.\n9.1.2. Hypermedia\nOriginally the hypermedia term was mostly used for linked data, in the sense of hyperlinks.\nIn REST, eventually, it also includes information for interaction and resource manipulation.\nHypermedia can be dynamic or static but regardless they are not considered part of the response data, because they define\nways to interact with the data.\nHypermedia is a very broad term and needs to be broken down in different parts.\nAlthough there isn’t any clear definition or consensus in the literature and the community, we will try to provide definitions and descriptions for\nall the different types of Hypermedia, according to our model’s perception.\n9.1.2.1. Liens\nThe most basic class of hypermedia, basically URIs that can be used to provide linking between related resources to the primary resource.\nThe properties of a link, like placement inside the response, strictly follow the semantics of the Media Type agreed.\n9.1.2.2. actes\nActions are links along with information for manipulating a resource.\nAlthough CRUD are the most popular actions of a resource, the beauty with REST, and consequently with Introspected REST,\nis that actions can go beyond plain CRUD.\nIn fact, we can define any type of action or meta-action of our internal resource, through the representation that we expose.\nAs a result, actions of a resource could be quite complex or simplistic depending on the needs and decisions of the API designer.\nActions should also describe any relevant information for the client to perform it, unless the Media Type itself describe those details.\n9.1.2.3. Forms\nAnother way of describing the manipulation options of a resource is the notion of forms.\nThe difference between actions and forms is that the latter are strictly semantically equivalent to an HTML form,\nfor the client to render.\n9.1.3. Metadata\nIf hypermedia is links and actions, then what is metadata ?\nMetadata are information about the resource that is not related with the data, including hypermedia.\nIn essence, metadata is a superset of hypermedia and it’s crucial for the client\nto understand API’s responses, access the API’s capabilities and manipulate the resources.\nMetadata could be API-specific, resource-specific, action-specific or even object-specific.\nThere could also be different kinds of metadata: runtime (i.e. pagination information), structural (i.e. data types of a resource object),\nhypermedia (i.e. links, actions, forms), informational targeted to humans (i.e. general information, descriptions), etc.\nUsually metadata is much less volatile than data, if not static, except runtime metadata\nthat depend on the request and the resource at the given time and state respectively.\n9.2. MicroTypes: reusable modules composing a Media Type
"},{"id":"text-86","type":"text","heading":"","plain_text":"Imagine how poor the Web would have been if we had limited HTML to what was\nneeded by an FTP client. That’s what most JSON APIs are today.\n— Roy Fielding, on Gazouillement, 27 Aug 2016","html":"Imagine how poor the Web would have been if we had limited HTML to what was\nneeded by an FTP client. That’s what most JSON APIs are today.\n— Roy Fielding, on Gazouillement, 27 Aug 2016
"},{"id":"text-87","type":"text","heading":"","plain_text":"We have been talking so much about the concept of MicroTypes but what exactly are ?\nCurrently, Media Types act as big monoliths that clients need to understand beforehand through human involvement.\nWe believe that Media Types should be broken in smaller\nreusable media types, MicroTypes, each describing very carefully a specific functionality of a modern API.\nThe reasoning is that, in our experience, we have seen that different APIs and API specs define the same functionalities in similar,\nbut not identical, ways.\nExamples of MicroTypes could be semantics for:","html":"We have been talking so much about the concept of MicroTypes but what exactly are ?\nCurrently, Media Types act as big monoliths that clients need to understand beforehand through human involvement.\nWe believe that Media Types should be broken in smaller\nreusable media types, MicroTypes, each describing very carefully a specific functionality of a modern API.\nThe reasoning is that, in our experience, we have seen that different APIs and API specs define the same functionalities in similar,\nbut not identical, ways.\nExamples of MicroTypes could be semantics for:
"},{"id":"text-88","type":"text","heading":"","plain_text":"pagination\nquerying over url (applying filters, aggregations, pagination/sorting on a resource),\nresource/association inclusion in the same response\nsemantic/linked data\nhypermedia actions (required fields, available fields),\ndata types and resource schemas\ninformation d'erreur\nand more advanced, like HTTP/2 server push for specific resources/states etc","html":"pagination\nquerying over url (applying filters, aggregations, pagination/sorting on a resource),\nresource/association inclusion in the same response\nsemantic/linked data\nhypermedia actions (required fields, available fields),\ndata types and resource schemas\ninformation d'erreur\nand more advanced, like HTTP/2 server push for specific resources/states etc
"},{"id":"text-89","type":"text","heading":"","plain_text":"Each one of these could be defined as separate MicroTypes that specify in isolation how that part of the API works.\nAt the same time they should be generic enough or follow some specific semantics so that it’s possible to be referenced parent\nMedia Types targeted for Introspected APIs.\nThe parent Media Type doesn’t need to know in advance all the MicroTypes that the API designer intends to use\nbecause that would mean that adding new MicroTypes would require a new parent Media Type which consequently means breaking the clients.\nInstead, each MicroType should be attachable to a parent Media Type that defines introspected behavior and clients\nwould take into account only MicroTypes that are programmed to understand.\n9.2.1. Benefits of MicroTypes\nThe benefits when leveraging such architecture are multi-fold.\n9.2.1.1. Granular parameterization of API functionality by clients\nFirst, by allowing the client and server to do the regular negotiation flow even for those sub-media-types, the communication\nbetween the 2 ends is parameterized to the needs of the client, down to the semantics level.\nFor instance, a server might provide 3 MicroTypes for error information, each one having different representation or semantics.\nBy letting the server to decide the appropriate MicroType for the client by analyzing the client’s incoming request,\nmight not be efficient as the client can only send a part of its properties through the request, for various reasons like privacy concerns and performance,\nand thus the server has partial knowledge of the client’s state and properties.\nThe server has to make an arbitrary choice for the client, what it thinks it’s thinks best, using this partial knowledge.\nInstead, by giving the client the option to negotiate parts of the API functionality, we shift the responsibility towards the client\nto select the best representation and semantics of various, isolated, API functionalities.\nGiven that the client can know much more about its needs than the server, it will make the best available choice\nfor each API functionality, from the server’s options, which eventually will lead to the optimized combination of\nMicroTypes.\nAs we will see later, in HTTP protocol, this is called reactive negotiation, a forgotten but still valid negotiation mechanism.\n9.2.1.2. Reusability\nSecondly, the MicroTypes specs and possibly implementations can be re-used by both the servers and clients.\nInstead of defining a whole Media Type, API designers will be able to include various small modules\nthat extend the API functionality they way it’s needed.\nWe firmly believe that once the community defines a number of MicroTypes, it will be much easier for an API designer\nto design a new API by reusing the MicroTypes she thinks fit best to her needs.\n9.2.2. MicroType shims\nImagine that we want to use an existing spec as a MicroType, like JSON Schema.\nWe cannot create a MicroType out of it with just a reference\nto the original spec because it lacks the context of the underlying protocol (like HTTP) and Media Type with which it will be\nutilisé.\nIt also lacks information about the requirements of the parent Media Type and the compatibility with other MicroTypes.\nInstead, we need to extend the original spec with the necessary, additional, semantics in the context\nof Media Types.\nThose semantics should be as minimal as possible, with respect to the initial specification and without altering its core semantics\nbut enough for usage in its new context.\nWhen this method is followed, the new MicroType is called a “wrapper” or a “shim” of the original spec.\n9.3. Introspection as the engine of application state (IATEOAS)\nThe idea of introspection is to be able to examine properties of a system at runtime.\nIn the case of Introspected REST, introspection defines a process for a client to be able to introspect\nthe API’s, resource’s, action’s or even object’s metadata at runtime.\nThrough those metadata, server provides all the available states, manipulation actions as well as the available transitions.\nThe implementation of the process is up to the API designer although usually a RESTish interface even for each MicroType’s metadata is a wise choice.\nIn any case, we would like to point out some key properties that should appear on any introspection process.\n9.3.1. Composability over monoliths\nThe process should embrace the use of distinct MicroTypes to form a Media Type instead of using a single Media Type.\nSuch an architecture will lead to a system whose each MicroType’s metadata is independent, self-contained and detached from the metadata\nof the rest MicroTypes.\nThe API designer should premier investigate and embrace the use of MicroTypes, RFCs and specs that are already defined and published, instead of\ncreating her own custom, unpublished spec.\nThe reason for this suggestion is that creating a new spec is difficult and usually such custom specs are used only for domain-specific APIs that\nwere created for and live as long as this API is used.\nInstead, by trying to adapt published, battle-tested, RFC-community-reviewed specs assures the API designer in terms of compatibility,\nadoptability, clarity and possibly implementation, for both ends of the communication.\n9.3.2. Plain data separated from metadata\nThe process of introspection should be distinctly different from requesting data.\nTo that extend, introspection responses should not include any data but only metadata, and data\nresponses should not include any metadata, except, possibly, runtime metadata.\n9.3.3. Identifiable metadata of each Microtype\nGiven that metadata are already separated from plain data, by being able to identify and retrieve metadata\nof a specific MicroType there are various advantages because each MicroType becomes independent and self-sufficient.\nPar exemple, mise en cache will be possible using the underlying protocol’s mechanisms, for each metadata type separately.\nAnother example is the detached evolvability of each MicroType’s metadata, independently, given that the MicroType’s semantics permit that.\n9.3.4. Discovery of resource capabilities\nAn Introspected REST API devrait fournir capabilities discovery per resource that provides\nall the necessary information to the client to understand what it is possible to request from the API.\n9.3.5. Client bootstraping\nAn Introspected REST API devrait fournir un API-wide capabilities discovery that lists all MicroTypes that are used API-wide along\nwith resources that can be accessed directly and in general, any information that could be of interest and could help the client\nto bootstrap faster.\nThe location of this detailed list should be in the conceptual racine resource/URL of the API.\n9.3.6. Automatic documentation generation\nPossibly the API will provide a MicroType targeted to humans and not machines that contains informational descriptions and explanations.\nIl convient de noter que this information must not be needed for a client to parse and understand the API responses,\nand even for humans such information should weight very little compared to the rest metadata.\nIn the same way, the API should automate the generation of the documentation using all metadata from all MicroTypes for every resource.\nThe way the documentation is requested and its format should be distinctly defined by a MicroType or the parent Media Type.\n10. Introspected REST applied to HTTP\nIntrospected REST architectural style is not bound to any protocol or spec, just as is REST.\nHere we will review the challenges that are rising through its adaptation in HTTP protocol.\nFor instance, we need to solve issues like announcement and negotiation of MicroTypes bound to a Media Type,\npriority order in case of overlaps or collisions, identification, and\nthe actual introspection process in HTTP.\n10.1 Revisiting content negotiation in HTTP\nAs we have already seen, content negotiation in HTTP is achieved through Acceptez request header but it’s not the\nonly header which can be used by the server to determine the appropriate representation for the client.\nAccept-Charset, Accepter l'encodage, Accept-Language request headers can also be used.\nIn practice, User-Agent header is also used by the server for choosing the right content for the client\nbecause it contains some device and agent characteristics, although it’s not part of the standard negotiation headers.\nLately even, a new draft standard is being created, HTTP Client Hints,\nthat extends the HTTP with new request headers which indicate device and agent characteristics.\nThe server uses all those headers as hints in order to determine the most suitable representation of the content\nto be served to the client.\nThis hint-based mechanism, which according to RFC 7231 is called server-driven\nor proactive content negotiation, has been extensively used in HTTP protocol.\nIn the context of MicroTypes and Introspected REST, using this mechanism, the client\ncan negotiate for runtime MicroTypes: API functionalities that define semantics\nfor the data and runtime metadata.\nThis type of MicroTypes, should tend to appear less often because\nif anything can be introspected on the side instead of runtime, it will be\ndefined as non-runtime, introspective metadata.\nInterestingly, RFC 7231 notes that proactive negotiation has\nsome serious disadvantages:","html":"Each one of these could be defined as separate MicroTypes that specify in isolation how that part of the API works.\nAt the same time they should be generic enough or follow some specific semantics so that it’s possible to be referenced parent\nMedia Types targeted for Introspected APIs.\nThe parent Media Type doesn’t need to know in advance all the MicroTypes that the API designer intends to use\nbecause that would mean that adding new MicroTypes would require a new parent Media Type which consequently means breaking the clients.\nInstead, each MicroType should be attachable to a parent Media Type that defines introspected behavior and clients\nwould take into account only MicroTypes that are programmed to understand.\n9.2.1. Benefits of MicroTypes\nThe benefits when leveraging such architecture are multi-fold.\n9.2.1.1. Granular parameterization of API functionality by clients\nFirst, by allowing the client and server to do the regular negotiation flow even for those sub-media-types, the communication\nbetween the 2 ends is parameterized to the needs of the client, down to the semantics level.\nFor instance, a server might provide 3 MicroTypes for error information, each one having different representation or semantics.\nBy letting the server to decide the appropriate MicroType for the client by analyzing the client’s incoming request,\nmight not be efficient as the client can only send a part of its properties through the request, for various reasons like privacy concerns and performance,\nand thus the server has partial knowledge of the client’s state and properties.\nThe server has to make an arbitrary choice for the client, what it thinks it’s thinks best, using this partial knowledge.\nInstead, by giving the client the option to negotiate parts of the API functionality, we shift the responsibility towards the client\nto select the best representation and semantics of various, isolated, API functionalities.\nGiven that the client can know much more about its needs than the server, it will make the best available choice\nfor each API functionality, from the server’s options, which eventually will lead to the optimized combination of\nMicroTypes.\nAs we will see later, in HTTP protocol, this is called reactive negotiation, a forgotten but still valid negotiation mechanism.\n9.2.1.2. Reusability\nSecondly, the MicroTypes specs and possibly implementations can be re-used by both the servers and clients.\nInstead of defining a whole Media Type, API designers will be able to include various small modules\nthat extend the API functionality they way it’s needed.\nWe firmly believe that once the community defines a number of MicroTypes, it will be much easier for an API designer\nto design a new API by reusing the MicroTypes she thinks fit best to her needs.\n9.2.2. MicroType shims\nImagine that we want to use an existing spec as a MicroType, like JSON Schema.\nWe cannot create a MicroType out of it with just a reference\nto the original spec because it lacks the context of the underlying protocol (like HTTP) and Media Type with which it will be\nutilisé.\nIt also lacks information about the requirements of the parent Media Type and the compatibility with other MicroTypes.\nInstead, we need to extend the original spec with the necessary, additional, semantics in the context\nof Media Types.\nThose semantics should be as minimal as possible, with respect to the initial specification and without altering its core semantics\nbut enough for usage in its new context.\nWhen this method is followed, the new MicroType is called a “wrapper” or a “shim” of the original spec.\n9.3. Introspection as the engine of application state (IATEOAS)\nThe idea of introspection is to be able to examine properties of a system at runtime.\nIn the case of Introspected REST, introspection defines a process for a client to be able to introspect\nthe API’s, resource’s, action’s or even object’s metadata at runtime.\nThrough those metadata, server provides all the available states, manipulation actions as well as the available transitions.\nThe implementation of the process is up to the API designer although usually a RESTish interface even for each MicroType’s metadata is a wise choice.\nIn any case, we would like to point out some key properties that should appear on any introspection process.\n9.3.1. Composability over monoliths\nThe process should embrace the use of distinct MicroTypes to form a Media Type instead of using a single Media Type.\nSuch an architecture will lead to a system whose each MicroType’s metadata is independent, self-contained and detached from the metadata\nof the rest MicroTypes.\nThe API designer should premier investigate and embrace the use of MicroTypes, RFCs and specs that are already defined and published, instead of\ncreating her own custom, unpublished spec.\nThe reason for this suggestion is that creating a new spec is difficult and usually such custom specs are used only for domain-specific APIs that\nwere created for and live as long as this API is used.\nInstead, by trying to adapt published, battle-tested, RFC-community-reviewed specs assures the API designer in terms of compatibility,\nadoptability, clarity and possibly implementation, for both ends of the communication.\n9.3.2. Plain data separated from metadata\nThe process of introspection should be distinctly different from requesting data.\nTo that extend, introspection responses should not include any data but only metadata, and data\nresponses should not include any metadata, except, possibly, runtime metadata.\n9.3.3. Identifiable metadata of each Microtype\nGiven that metadata are already separated from plain data, by being able to identify and retrieve metadata\nof a specific MicroType there are various advantages because each MicroType becomes independent and self-sufficient.\nPar exemple, mise en cache will be possible using the underlying protocol’s mechanisms, for each metadata type separately.\nAnother example is the detached evolvability of each MicroType’s metadata, independently, given that the MicroType’s semantics permit that.\n9.3.4. Discovery of resource capabilities\nAn Introspected REST API devrait fournir capabilities discovery per resource that provides\nall the necessary information to the client to understand what it is possible to request from the API.\n9.3.5. Client bootstraping\nAn Introspected REST API devrait fournir un API-wide capabilities discovery that lists all MicroTypes that are used API-wide along\nwith resources that can be accessed directly and in general, any information that could be of interest and could help the client\nto bootstrap faster.\nThe location of this detailed list should be in the conceptual racine resource/URL of the API.\n9.3.6. Automatic documentation generation\nPossibly the API will provide a MicroType targeted to humans and not machines that contains informational descriptions and explanations.\nIl convient de noter que this information must not be needed for a client to parse and understand the API responses,\nand even for humans such information should weight very little compared to the rest metadata.\nIn the same way, the API should automate the generation of the documentation using all metadata from all MicroTypes for every resource.\nThe way the documentation is requested and its format should be distinctly defined by a MicroType or the parent Media Type.\n10. Introspected REST applied to HTTP\nIntrospected REST architectural style is not bound to any protocol or spec, just as is REST.\nHere we will review the challenges that are rising through its adaptation in HTTP protocol.\nFor instance, we need to solve issues like announcement and negotiation of MicroTypes bound to a Media Type,\npriority order in case of overlaps or collisions, identification, and\nthe actual introspection process in HTTP.\n10.1 Revisiting content negotiation in HTTP\nAs we have already seen, content negotiation in HTTP is achieved through Acceptez request header but it’s not the\nonly header which can be used by the server to determine the appropriate representation for the client.\nAccept-Charset, Accepter l'encodage, Accept-Language request headers can also be used.\nIn practice, User-Agent header is also used by the server for choosing the right content for the client\nbecause it contains some device and agent characteristics, although it’s not part of the standard negotiation headers.\nLately even, a new draft standard is being created, HTTP Client Hints,\nthat extends the HTTP with new request headers which indicate device and agent characteristics.\nThe server uses all those headers as hints in order to determine the most suitable representation of the content\nto be served to the client.\nThis hint-based mechanism, which according to RFC 7231 is called server-driven\nor proactive content negotiation, has been extensively used in HTTP protocol.\nIn the context of MicroTypes and Introspected REST, using this mechanism, the client\ncan negotiate for runtime MicroTypes: API functionalities that define semantics\nfor the data and runtime metadata.\nThis type of MicroTypes, should tend to appear less often because\nif anything can be introspected on the side instead of runtime, it will be\ndefined as non-runtime, introspective metadata.\nInterestingly, RFC 7231 notes that proactive negotiation has\nsome serious disadvantages:
"},{"id":"text-90","type":"text","heading":"","plain_text":"Proactive negotiation has serious disadvantages:\no It is impossible for the server to accurately determine what might\n be “best” for any given user, since that would require complete\n knowledge of both the capabilities of the user agent and the\n intended use for the response (e.g., does the user want to view it\n on screen or print it on paper?);\no Having the user agent describe its capabilities in every request\n can be both very inefficient (given that only a small percentage\n of responses have multiple representations) and a potential risk\n to the user’s privacy;\no It complicates the implementation of an origin server and the\n algorithms for generating responses to a request; et,\no It limits the reusability of responses for shared caching.\n— RFC 7231","html":"Proactive negotiation has serious disadvantages:\no It is impossible for the server to accurately determine what might\n be “best” for any given user, since that would require complete\n knowledge of both the capabilities of the user agent and the\n intended use for the response (e.g., does the user want to view it\n on screen or print it on paper?);\no Having the user agent describe its capabilities in every request\n can be both very inefficient (given that only a small percentage\n of responses have multiple representations) and a potential risk\n to the user’s privacy;\no It complicates the implementation of an origin server and the\n algorithms for generating responses to a request; et,\no It limits the reusability of responses for shared caching.\n— RFC 7231
"},{"id":"text-91","type":"text","heading":"","plain_text":"In fact, from the beginnings of HTTP (since RFC 2068, published in 1997),\nthe protocol allowed another negotiation type: agent-driven or reactive content negotiation negotiation,\nthat matches very well our introspective concept.\nAs RFC 7231 notes, in reactive content negotiation the server provides a\nlist of options to the client to choose from.","html":"In fact, from the beginnings of HTTP (since RFC 2068, published in 1997),\nthe protocol allowed another negotiation type: agent-driven or reactive content negotiation negotiation,\nthat matches very well our introspective concept.\nAs RFC 7231 notes, in reactive content negotiation the server provides a\nlist of options to the client to choose from.
"},{"id":"text-92","type":"text","heading":"","plain_text":"With reactive negotiation (a.k.a., agent-driven negotiation),\n selection of the best response representation (regardless of the\n status code) is performed by the user agent after receiving an\n initial response from the origin server that contains a list of\n resources for alternative representations.\n(…)\nA server might choose not to send an initial representation, other\n than the list of alternatives, and thereby indicate that reactive\n negotiation by the user agent is preferred. Par exemple, le\n alternatives listed in responses with the 300 (Multiple Choices) and\n 406 (Not Acceptable) status codes include information about the\n available representations so that the user or user agent can react by\n making a selection.\n— RFC 7231","html":"With reactive negotiation (a.k.a., agent-driven negotiation),\n selection of the best response representation (regardless of the\n status code) is performed by the user agent after receiving an\n initial response from the origin server that contains a list of\n resources for alternative representations.\n(…)\nA server might choose not to send an initial representation, other\n than the list of alternatives, and thereby indicate that reactive\n negotiation by the user agent is preferred. Par exemple, le\n alternatives listed in responses with the 300 (Multiple Choices) and\n 406 (Not Acceptable) status codes include information about the\n available representations so that the user or user agent can react by\n making a selection.\n— RFC 7231
"},{"id":"text-93","type":"text","heading":"","plain_text":"With reactive negotiation, the client is responsible for choosing the most appropriate representation,\naccording to its needs.\nThat goes inline with Introspective REST, as the client, after receiving all the possible server options,\nuses the ones that best fit to its use case or understands better.\nAs the RFC notes, such negotiation has the advantage of choosing the best combination of MicroTypes,\nbecause the client does the selection out of a predefined list that the server publishes.\n10.2. Runtime MicroTypes\nRuntime MicroTypes are targeted for API functionality that is used during the request/response cycle\nof plain data.\nSuch functionality could be pagination, URI querying language, error descriptions etc or it could even be\nsemantics around the data itself.\nIt should also be noted that even runtime MicroTypes could have content for introspection but the key difference\nfrom pure introspective MicroTypes is that part of their functionality affects the semantics of the client’s request\nor server’s response.\nThe negotiation of runtime MicroTypes should follow the regular negotiation flow:\nThe client should negotiate for the principal Media Type using the Acceptez demande\nheader and the server responds with Type de contenu response header, denoting the selected representation.\nHowever the key difference is that for each principal Media Type, it should also\nnegotiate for the MicroTypes to be used with it.\nFor that, we will employ the Media Type parameters, a rarely used mechanism:","html":"With reactive negotiation, the client is responsible for choosing the most appropriate representation,\naccording to its needs.\nThat goes inline with Introspective REST, as the client, after receiving all the possible server options,\nuses the ones that best fit to its use case or understands better.\nAs the RFC notes, such negotiation has the advantage of choosing the best combination of MicroTypes,\nbecause the client does the selection out of a predefined list that the server publishes.\n10.2. Runtime MicroTypes\nRuntime MicroTypes are targeted for API functionality that is used during the request/response cycle\nof plain data.\nSuch functionality could be pagination, URI querying language, error descriptions etc or it could even be\nsemantics around the data itself.\nIt should also be noted that even runtime MicroTypes could have content for introspection but the key difference\nfrom pure introspective MicroTypes is that part of their functionality affects the semantics of the client’s request\nor server’s response.\nThe negotiation of runtime MicroTypes should follow the regular negotiation flow:\nThe client should negotiate for the principal Media Type using the Acceptez demande\nheader and the server responds with Type de contenu response header, denoting the selected representation.\nHowever the key difference is that for each principal Media Type, it should also\nnegotiate for the MicroTypes to be used with it.\nFor that, we will employ the Media Type parameters, a rarely used mechanism:
"},{"id":"text-94","type":"text","heading":"","plain_text":"Media types MAY elect to use one or more media type parameters, or\n some parameters may be automatically made available to the media type\n by virtue of being a subtype of a content type that defines a set of\n parameters applicable to any of its subtypes. In either case, the\n names, values, and meanings of any parameters MUST be fully specified\n when a media type is registered in the standards tree, and SHOULD be\n specified as completely as possible when media types are registered\n in the vendor or personal trees.\nParameter names have the syntax as media type names and values:","html":"Media types MAY elect to use one or more media type parameters, or\n some parameters may be automatically made available to the media type\n by virtue of being a subtype of a content type that defines a set of\n parameters applicable to any of its subtypes. In either case, the\n names, values, and meanings of any parameters MUST be fully specified\n when a media type is registered in the standards tree, and SHOULD be\n specified as completely as possible when media types are registered\n in the vendor or personal trees.\nParameter names have the syntax as media type names and values:
"},{"id":"text-95","type":"text","heading":"","plain_text":"parameter-name = restricted-name","html":"parameter-name = restricted-name
"},{"id":"text-96","type":"text","heading":"","plain_text":"— RFC 6838","html":"— RFC 6838
"},{"id":"text-97","type":"text","heading":"","plain_text":"An example of an imaginary Media Type with a couple of parameters for MicroTypes is:","html":"An example of an imaginary Media Type with a couple of parameters for MicroTypes is:
"},{"id":"text-98","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql;","html":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql;
"},{"id":"text-99","type":"text","heading":"","plain_text":"In the aforementioned example, the client asks for representation of application/vnd.api+json,\n(which as we have seen earlier it vaguely means a vendor application that follows the semantics of api, in JSON representation)\nbut wants the pagination to follow the semantics of simple-spec and the querying language of graphql.\nThe client should be able to even set a preference order:","html":"In the aforementioned example, the client asks for representation of application/vnd.api+json,\n(which as we have seen earlier it vaguely means a vendor application that follows the semantics of api, in JSON representation)\nbut wants the pagination to follow the semantics of simple-spec and the querying language of graphql.\nThe client should be able to even set a preference order:
"},{"id":"text-100","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi;","html":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi;
"},{"id":"text-101","type":"text","heading":"","plain_text":"Here the client shows preference to the imaginary graphql querying language but if that doesn’t exist\nthen it will accept the jsonapi querying language.\nIt should be noted that this preference is different from a Media Type preference using the relative\npoids q parameter (also called quality value) as it applies to the MicroType level.\nAn example with multiple Media Types could be:","html":"Here the client shows preference to the imaginary graphql querying language but if that doesn’t exist\nthen it will accept the jsonapi querying language.\nIt should be noted that this preference is different from a Media Type preference using the relative\npoids q parameter (also called quality value) as it applies to the MicroType level.\nAn example with multiple Media Types could be:
"},{"id":"text-102","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi, application/vnd.api2+json; pagination=simple-spec; querying=jsonapi; querying=jsonapi; q=0.9","html":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi, application/vnd.api2+json; pagination=simple-spec; querying=jsonapi; querying=jsonapi; q=0.9
"},{"id":"text-103","type":"text","heading":"","plain_text":"In this example the client shows preference to the application/vnd.api+json Media Type (it has default quality value of 1.0)\nwith specific preferences on MicroType level, as we explained above.\nHowever if this Media Type is not available then it will accept the next most preferred, application/vnd.api2+json, by requesting\nspecific MicroTypes.\nIf the server can provide only the less preferred Media Type with the less preferred querying it would answer:","html":"In this example the client shows preference to the application/vnd.api+json Media Type (it has default quality value of 1.0)\nwith specific preferences on MicroType level, as we explained above.\nHowever if this Media Type is not available then it will accept the next most preferred, application/vnd.api2+json, by requesting\nspecific MicroTypes.\nIf the server can provide only the less preferred Media Type with the less preferred querying it would answer:
"},{"id":"text-104","type":"text","heading":"","plain_text":"Content-Type: application/vnd.api2+json; pagination=simple-spec; querying=graphql","html":"Content-Type: application/vnd.api2+json; pagination=simple-spec; querying=graphql
"},{"id":"text-105","type":"text","heading":"","plain_text":"10.3. Introspective MicroTypes\nIntrospective MicroTypes don’t alter the semantics of request/response cycle but are still valuable to the client\nand the decisions they should take based on the current state and the input from the application developer.\nThey can provide information about the data types, RDF Schema of the resources, etc.\nIntrospective MicroTypes should employ reactive negotiation.\nThe question though is how can the server advertise the availability of MicroTypes for the client\nto introspect.\nIdeally we would like to inform the client for all possible options through HTTP instead of employing a serialization format.\nUnfortunately, the HTTP protocol doesn’t say much about this type of negotiation, only that the status code when requesting\nsuch information should be 300 and Lien relation header of RFC 5988 could be potentially used\nto provide the list with all the available options,\nmostly for historical reasons that date back to RFC 2068:","html":"10.3. Introspective MicroTypes\nIntrospective MicroTypes don’t alter the semantics of request/response cycle but are still valuable to the client\nand the decisions they should take based on the current state and the input from the application developer.\nThey can provide information about the data types, RDF Schema of the resources, etc.\nIntrospective MicroTypes should employ reactive negotiation.\nThe question though is how can the server advertise the availability of MicroTypes for the client\nto introspect.\nIdeally we would like to inform the client for all possible options through HTTP instead of employing a serialization format.\nUnfortunately, the HTTP protocol doesn’t say much about this type of negotiation, only that the status code when requesting\nsuch information should be 300 and Lien relation header of RFC 5988 could be potentially used\nto provide the list with all the available options,\nmostly for historical reasons that date back to RFC 2068:
"},{"id":"text-106","type":"text","heading":"","plain_text":"The 300 (Multiple Choices) status code indicates that the target\n resource has more than one representation, each with its own more\n specific identifier, and information about the alternatives is being\n provided so that the user (or user agent) can select a preferred\n representation by redirecting its request to one or more of those\n identifiers. In other words, the server desires that the user agent\n engage in reactive negotiation to select the most appropriate\n representation(s) for its needs (Section 3.4). (…)\nFor request methods other than HEAD, the server SHOULD generate a\n payload in the 300 response containing a list of representation\n metadata and URI reference(s) from which the user or user agent can\n choose the one most preferred. (…)\nNote: The original proposal for the 300 status code defined the\n URI header field as providing a list of alternative\n representations, such that it would be usable for 200, 300, and\n 406 responses and be transferred in responses to the HEAD method.\n However, lack of deployment and disagreement over syntax led to\n both URI and Alternates (a subsequent proposal) being dropped from\n this specification. It is possible to communicate the list using\n a set of Link header fields [RFC5988], each with a relationship of\n “alternate”, though deployment is a chicken-and-egg problem.\n— RFC 7231","html":"The 300 (Multiple Choices) status code indicates that the target\n resource has more than one representation, each with its own more\n specific identifier, and information about the alternatives is being\n provided so that the user (or user agent) can select a preferred\n representation by redirecting its request to one or more of those\n identifiers. In other words, the server desires that the user agent\n engage in reactive negotiation to select the most appropriate\n representation(s) for its needs (Section 3.4). (…)\nFor request methods other than HEAD, the server SHOULD generate a\n payload in the 300 response containing a list of representation\n metadata and URI reference(s) from which the user or user agent can\n choose the one most preferred. (…)\nNote: The original proposal for the 300 status code defined the\n URI header field as providing a list of alternative\n representations, such that it would be usable for 200, 300, and\n 406 responses and be transferred in responses to the HEAD method.\n However, lack of deployment and disagreement over syntax led to\n both URI and Alternates (a subsequent proposal) being dropped from\n this specification. It is possible to communicate the list using\n a set of Link header fields [RFC5988], each with a relationship of\n “alternate”, though deployment is a chicken-and-egg problem.\n— RFC 7231
"},{"id":"text-107","type":"text","heading":"","plain_text":"To our knowledge, reactive negotiation has never been analyzed, used or suggested before.\nHere, apart from Lien relation header, we also suggest two more alternative implementation to solve\nthis issue and we will let the community to choose what is the more appropriate solution.\n10.4.1 The HTTP OPTIONS method\nThe server can describe the meta-data of a resource in the response body of the OPTIONS demande.\nIn fact, OPTIONS method has historically been used for getting information on methods supported on a specific resource.\nAccording to RFC 7231 this method should be used to\ndetermine the capabilities of the server for the targeted resource:","html":"To our knowledge, reactive negotiation has never been analyzed, used or suggested before.\nHere, apart from Lien relation header, we also suggest two more alternative implementation to solve\nthis issue and we will let the community to choose what is the more appropriate solution.\n10.4.1 The HTTP OPTIONS method\nThe server can describe the meta-data of a resource in the response body of the OPTIONS demande.\nIn fact, OPTIONS method has historically been used for getting information on methods supported on a specific resource.\nAccording to RFC 7231 this method should be used to\ndetermine the capabilities of the server for the targeted resource:
"},{"id":"text-108","type":"text","heading":"","plain_text":"The OPTIONS method requests information about the communication\noptions available for the target resource, at either the origin\nserver or an intervening intermediary. This method allows a client\nto determine the options and/or requirements associated with a\nresource, or the capabilities of a server, without implying a\nresource action.\n— RFC 7231","html":"The OPTIONS method requests information about the communication\noptions available for the target resource, at either the origin\nserver or an intervening intermediary. This method allows a client\nto determine the options and/or requirements associated with a\nresource, or the capabilities of a server, without implying a\nresource action.\n— RFC 7231
"},{"id":"text-109","type":"text","heading":"","plain_text":"The OPTIONS method could be used for the server to provide a list of available introspective MicroTypes\nand let the client choose what it thinks best.\nThe same RFC mentions that there isn’t any practical use of sending an OPTIONS request\nto the root url.","html":"The OPTIONS method could be used for the server to provide a list of available introspective MicroTypes\nand let the client choose what it thinks best.\nThe same RFC mentions that there isn’t any practical use of sending an OPTIONS request\nto the root url.
"},{"id":"text-110","type":"text","heading":"","plain_text":"An OPTIONS request with an asterisk (“*”) as the request-target\n(Section 5.3 of [RFC7230]) applies to the server in general rather\nthan to a specific resource. Since a server’s communication options\ntypically depend on the resource, the “*” request is only useful as a\n“ping” or “no-op” type of method; it does nothing beyond allowing the\nclient to test the capabilities of the server. For example, this can\nbe used to test a proxy for HTTP/1.1 conformance (or lack thereof).\n— RFC 7231","html":"An OPTIONS request with an asterisk (“*”) as the request-target\n(Section 5.3 of [RFC7230]) applies to the server in general rather\nthan to a specific resource. Since a server’s communication options\ntypically depend on the resource, the “*” request is only useful as a\n“ping” or “no-op” type of method; it does nothing beyond allowing the\nclient to test the capabilities of the server. For example, this can\nbe used to test a proxy for HTTP/1.1 conformance (or lack thereof).\n— RFC 7231
"},{"id":"text-111","type":"text","heading":"","plain_text":"However, we feel that this is the perfect case for hosting an API’s discovery for available capabilities using\nreactive negotiation.\nWe could keep the / * for “ping” or “no-op” type of method as the RFC notes and have the root\n/ for listing all API’s capabilities through MicroTypes for all resources, as IATEOAS denotes.\nNow that we know how to fetch the MicroTypes that the server offers, we need to find\nan appropriate representation for it.\nOne option is to employ a common JSON format for describing each MicroType, its URL for introspection along\nwith the expected Media Type the response in the specified URL uses.\nFor instance if we would like to introspect resource /api/users/1 of an API we would get the following\ninformation by sending an OPTIONS request to the resource’s url.","html":"However, we feel that this is the perfect case for hosting an API’s discovery for available capabilities using\nreactive negotiation.\nWe could keep the / * for “ping” or “no-op” type of method as the RFC notes and have the root\n/ for listing all API’s capabilities through MicroTypes for all resources, as IATEOAS denotes.\nNow that we know how to fetch the MicroTypes that the server offers, we need to find\nan appropriate representation for it.\nOne option is to employ a common JSON format for describing each MicroType, its URL for introspection along\nwith the expected Media Type the response in the specified URL uses.\nFor instance if we would like to introspect resource /api/users/1 of an API we would get the following\ninformation by sending an OPTIONS request to the resource’s url.
"},{"id":"text-112","type":"text","heading":"","plain_text":""JSON-Schema": \n "url": "/api/users/1?microtype=json-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json"\n ,\n "RDF": \n "url": "/api/users/1?microtype=rdf",\n "method": "OPTIONS",\n "content-type": "application/rdf+xml"\n ,\n "JSON-LD": \n "url": "api/users/1?microtype=json-ld",\n "method": "OPTIONS",\n "content-type": "application/ld+json"","html":""JSON-Schema": \n "url": "/api/users/1?microtype=json-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json"\n ,\n "RDF": \n "url": "/api/users/1?microtype=rdf",\n "method": "OPTIONS",\n "content-type": "application/rdf+xml"\n ,\n "JSON-LD": \n "url": "api/users/1?microtype=json-ld",\n "method": "OPTIONS",\n "content-type": "application/ld+json"
"},{"id":"text-113","type":"text","heading":"","plain_text":"The problem though is that such functionality (sending an OPTIONS demande à /api/users/1) must be described\nsomewhere so that the client knows where to look for it, possibly in the parent Media Type or using another MicroType.\nAn alternative option is to use the OPTIONS request in combination with the Lien header, as described later, that will announce\nthe MicroTypes availability. Such functionality should still be described somewhere as\nRFC 7231 only makes a suggestion for the Lien header usage.\nIt is our intention to advice the community to use this solution for the introspection process, without the Lien entête\nbut with a response body that describes the MicroTypes availability.\nThe structure and semantics of the response could be available in various serializations and formats and the clients could\nspecify their preference using the regular, proactive, HTTP negotiation flow of Media Types.\nAlthough, as we will see later, it comes at a cost, we feel that it’s the best among all three solutions presented here\nand the conceptual notion of OPTIONS method, as described by HTTP specs, matches very well with our intended use case.\nFurthermore, such process gives much more flexibility to append any additional information to the client, than\nan HTTP header.\n10.4.2. Well-known URIs and JSON Home\nRFC 5785 defines a pre-defined URI for accessing server’s various metadata:","html":"The problem though is that such functionality (sending an OPTIONS demande à /api/users/1) must be described\nsomewhere so that the client knows where to look for it, possibly in the parent Media Type or using another MicroType.\nAn alternative option is to use the OPTIONS request in combination with the Lien header, as described later, that will announce\nthe MicroTypes availability. Such functionality should still be described somewhere as\nRFC 7231 only makes a suggestion for the Lien header usage.\nIt is our intention to advice the community to use this solution for the introspection process, without the Lien entête\nbut with a response body that describes the MicroTypes availability.\nThe structure and semantics of the response could be available in various serializations and formats and the clients could\nspecify their preference using the regular, proactive, HTTP negotiation flow of Media Types.\nAlthough, as we will see later, it comes at a cost, we feel that it’s the best among all three solutions presented here\nand the conceptual notion of OPTIONS method, as described by HTTP specs, matches very well with our intended use case.\nFurthermore, such process gives much more flexibility to append any additional information to the client, than\nan HTTP header.\n10.4.2. Well-known URIs and JSON Home\nRFC 5785 defines a pre-defined URI for accessing server’s various metadata:
"},{"id":"text-114","type":"text","heading":"","plain_text":"It is increasingly common for Web-based protocols to require the\n discovery of policy or other information about a host (“site-wide\n metadata”) before making a request. For example, the Robots\n Exclusion Protocol http://www.robotstxt.org/ specifies a way for\n automated processes to obtain permission to access resources;\n likewise, the Platform for Privacy Preferences [W3C.REC-P3P-20020416]\n tells user-agents how to discover privacy policy beforehand. (…)\nWhen this happens, it is common to designate a “well-known location”\n for such data, so that it can be easily located. However, this\n approach has the drawback of risking collisions, both with other such\n designated “well-known locations” and with pre-existing resources.\nTo address this, this memo defines a path prefix in HTTP(S) URIs for\n these “well-known locations”, “/.well-known/”. Future specifications\n that need to define a resource for such site-wide metadata can\n register their use to avoid collisions and minimise impingement upon\n sites’ URI space.\n— RFC 5785","html":"It is increasingly common for Web-based protocols to require the\n discovery of policy or other information about a host (“site-wide\n metadata”) before making a request. For example, the Robots\n Exclusion Protocol http://www.robotstxt.org/ specifies a way for\n automated processes to obtain permission to access resources;\n likewise, the Platform for Privacy Preferences [W3C.REC-P3P-20020416]\n tells user-agents how to discover privacy policy beforehand. (…)\nWhen this happens, it is common to designate a “well-known location”\n for such data, so that it can be easily located. However, this\n approach has the drawback of risking collisions, both with other such\n designated “well-known locations” and with pre-existing resources.\nTo address this, this memo defines a path prefix in HTTP(S) URIs for\n these “well-known locations”, “/.well-known/”. Future specifications\n that need to define a resource for such site-wide metadata can\n register their use to avoid collisions and minimise impingement upon\n sites’ URI space.\n— RFC 5785
"},{"id":"text-115","type":"text","heading":"","plain_text":"Using this specification, the server can register a well-known\nURI that is expected to be the first URI the client requests to introspect.\nTo that extend, a new draft spec is being developed, JSON Home\nthat defines such document structure that provides all the server resources and capabilities.\nRegardless if JSON Home is used, well-known URIs can provide a way to introspect only the\nserver-wide capabilities:\nIci, métadonnées would be a new well-known URI registry that either defined in the parent Media Type\nor defined by itself as a MicroType.\nThe spec does not provide a scheme for well-known URIs per resource or nested URI and this means\nthat we need to build something upon well-known URIs functionality in order to provide\nintrospection per resource.\nHow this will be achieved can be defined by the community, if used eventually,\nbut a possible implementation could be to pass\nthe desired resource URL as a query in the métadonnées well-known URI registry:","html":"Using this specification, the server can register a well-known\nURI that is expected to be the first URI the client requests to introspect.\nTo that extend, a new draft spec is being developed, JSON Home\nthat defines such document structure that provides all the server resources and capabilities.\nRegardless if JSON Home is used, well-known URIs can provide a way to introspect only the\nserver-wide capabilities:\nIci, métadonnées would be a new well-known URI registry that either defined in the parent Media Type\nor defined by itself as a MicroType.\nThe spec does not provide a scheme for well-known URIs per resource or nested URI and this means\nthat we need to build something upon well-known URIs functionality in order to provide\nintrospection per resource.\nHow this will be achieved can be defined by the community, if used eventually,\nbut a possible implementation could be to pass\nthe desired resource URL as a query in the métadonnées well-known URI registry:
"},{"id":"text-116","type":"text","heading":"","plain_text":"/.well-known/metadata?query=/api/users/1","html":"/.well-known/metadata?query=/api/users/1
"},{"id":"text-117","type":"text","heading":"","plain_text":"Again as with HTTP OPTIONS, the server will either have to provide a representation\nof the available MicroTypes inside the response body of the well-known URI or use the Lien header.\nAlthough this solution could work, we feel that RFC 5785\nwas not designed to be used for such specific URIs but instead for more generic properties\nthat usually apply to the host itself.\nRegadless if HTTP OPTIONS or well-known URIs are used, Lien header, defined in RFC 5988,\nis an alternative way of publishing the available MicroTypes by the server,\nin a representation-agnostic way.","html":"Again as with HTTP OPTIONS, the server will either have to provide a representation\nof the available MicroTypes inside the response body of the well-known URI or use the Lien header.\nAlthough this solution could work, we feel that RFC 5785\nwas not designed to be used for such specific URIs but instead for more generic properties\nthat usually apply to the host itself.\nRegadless if HTTP OPTIONS or well-known URIs are used, Lien header, defined in RFC 5988,\nis an alternative way of publishing the available MicroTypes by the server,\nin a representation-agnostic way.
"},{"id":"text-118","type":"text","heading":"","plain_text":"A means of indicating the relationships between resources on the Web,\n as well as indicating the type of those relationships, has been\n available for some time in HTML [W3C.REC-html401-19991224], and more\n recently in Atom [RFC4287]. These mechanisms, although conceptually\n similar, are separately specified. However, links between resources\n need not be format specific; it can be useful to have typed links\n that are independent of their serialisation, especially when a\n resource has representations in multiple formats.\nTo this end, this document defines a framework for typed links that\n isn’t specific to a particular serialisation or application. Cela fait\n so by redefining the link relation registry established by Atom to\n have a broader domain, and adding to it the relations that are\n defined by HTML.\n— RFC 5988","html":"A means of indicating the relationships between resources on the Web,\n as well as indicating the type of those relationships, has been\n available for some time in HTML [W3C.REC-html401-19991224], and more\n recently in Atom [RFC4287]. These mechanisms, although conceptually\n similar, are separately specified. However, links between resources\n need not be format specific; it can be useful to have typed links\n that are independent of their serialisation, especially when a\n resource has representations in multiple formats.\nTo this end, this document defines a framework for typed links that\n isn’t specific to a particular serialisation or application. Cela fait\n so by redefining the link relation registry established by Atom to\n have a broader domain, and adding to it the relations that are\n defined by HTML.\n— RFC 5988
"},{"id":"text-119","type":"text","heading":"","plain_text":"As the next (draft) version of RFC 5988 notes:","html":"As the next (draft) version of RFC 5988 notes:
"},{"id":"text-120","type":"text","heading":"","plain_text":"a link published through Lien header can be viewed as a statement of the form\n“link context has a link relation type resource at link target, which has target attributes”.\n— rfc5988bis-07","html":"a link published through Lien header can be viewed as a statement of the form\n“link context has a link relation type resource at link target, which has target attributes”.\n— rfc5988bis-07
"},{"id":"text-121","type":"text","heading":"","plain_text":"As a result, this RFC provides us a representation-agnostic mechanism through which we can\nannounce link relations of the current visited URL, along with their relation types.\nFor instance, the following example","html":"As a result, this RFC provides us a representation-agnostic mechanism through which we can\nannounce link relations of the current visited URL, along with their relation types.\nFor instance, the following example
"},{"id":"text-122","type":"text","heading":"","plain_text":"Link: ; rel="previous";\n title="previous chapter"","html":"Link: ; rel="previous";\n title="previous chapter"
"},{"id":"text-123","type":"text","heading":"","plain_text":"would denote that that “chapter2” is previous to this resource in a logical\nnavigation path.\nNote that title is a target attribute or parameter to this link relation.\nIn the case of Introspected REST, we would use it to announce introspective MicroTypes related\nto the resource the client visits.\nBy exploiting the target attributes we would also like to specify the HTTP method and\noptionally the Media Type the client should expect in order to introspect\nthe given MicroType.","html":"would denote that that “chapter2” is previous to this resource in a logical\nnavigation path.\nNote that title is a target attribute or parameter to this link relation.\nIn the case of Introspected REST, we would use it to announce introspective MicroTypes related\nto the resource the client visits.\nBy exploiting the target attributes we would also like to specify the HTTP method and\noptionally the Media Type the client should expect in order to introspect\nthe given MicroType.
"},{"id":"text-124","type":"text","heading":"","plain_text":"Link: ; rel="microtype";\n method="options"; type="application/schema+json" name="json-schema",\n ; rel="microtype";\n method="options"; type="application/schema+json" name="rdf",\n ; rel="microtype";\n method="options"; type="application/schema+json" name="json-ld",","html":"Link: ; rel="microtype";\n method="options"; type="application/schema+json" name="json-schema",\n ; rel="microtype";\n method="options"; type="application/schema+json" name="rdf",\n ; rel="microtype";\n method="options"; type="application/schema+json" name="json-ld",
"},{"id":"text-125","type":"text","heading":"","plain_text":"Also related, Erik Wilde is working on an IETF draft, named Link Relation Types for Web Services\nthat defines a way to announce metadata of a resource through this mechanism.\nGiven that and also the fact that this solution has the advantage of solving the MicroTypes announcement\nin the HTTP protocol without being tied to a specific serialization, it’s easy to think that it’s the\nmost appropriate way to specify the MicroTypes supported on a specific resource.\nUnfortunately, this solution has a couple of drawbacks.\nFirst and foremost, the link header size is limited and if other headers of the response\nare already overloaded then the server might refuse to render the response to the client\nbut instead return an HTTP error possibly “413 Request Entity Too Large” or “414 Request-URI Too Long”\nalthough there isn’t an HTTP status code explicitly defined for such case.\nA possible solution to this could be Linkset: A Link Relation Type for Link Sets RFC proposal\n(a work also by Erik Wilde) but currently it’s in draft state.\nOnce published, a Linkset could group together a set of links and provide them to the client by reference.\nHowever Linksets don’t actually solve our issue because eventually the MicroTypes announcement would not\nbe solved in the HTTP level as a Linkset would have to provide a body format as well.\nAnother issue is that the server cannot specify a caching strategy for all links at once because there\nis no mechanism in HTTP which allows us to specify caching directives for specific headers only.\nAs a result, unless we used a Linkset which we can’t yet and would cancel any advantages that Lien header provides\ndue to the need of a response body,\nthe client would have to dereference all MicroTypes to figure out their caching properties.\nOn a side note, over the past few years, we have seen an explosion of link types\nused along with Lien header defined by RFC 5988.\nThe authors of Introspected REST are skeptical with this trend and feel that the Lien header should\nnot be overused.\nFor instance, having more than 5 links in the Lien header feels that something is wrong, probably too many things\nare defined in the protocol level whereas maybe they should be defined somewhere else.\nWe will let the community to decide if this approach is good for publishing MicroTypes but we would like to stress\nthe point that having a link in the HTTP level through Lien header might be better\nfor related resources that all clients would understand, which is not always the case in Introspected REST.\nThe API designer could add more MicroTypes, progressively, as the time passes and simultaneously,\nsome clients might not be interested or understand all MicroTypes of an Introspected REST.\nRequiring the client to receive all MicroType information for every data request is made\nwould probably be against the principles of Introspected REST.\n10.5. Considérations\n10.5.1 Diversifing from existing RFCs\nAlthough we have managed to apply Introspective REST to HTTP, a protocol that has been influenced so much\nby Roy’s REST model (and\nvice verca) this adaptation comes to a cost: we need to diversify from some RFCs specifications that we make use of.\nFortunately this diversification is relatively very small compared to the gains and all changes are\nbackwards compatible with existing deployed clients.\n10.5.1. HTTP OPTIONS responses are not cacheable\nFirst and most importantly, according to RFC 7231:","html":"Also related, Erik Wilde is working on an IETF draft, named Link Relation Types for Web Services\nthat defines a way to announce metadata of a resource through this mechanism.\nGiven that and also the fact that this solution has the advantage of solving the MicroTypes announcement\nin the HTTP protocol without being tied to a specific serialization, it’s easy to think that it’s the\nmost appropriate way to specify the MicroTypes supported on a specific resource.\nUnfortunately, this solution has a couple of drawbacks.\nFirst and foremost, the link header size is limited and if other headers of the response\nare already overloaded then the server might refuse to render the response to the client\nbut instead return an HTTP error possibly “413 Request Entity Too Large” or “414 Request-URI Too Long”\nalthough there isn’t an HTTP status code explicitly defined for such case.\nA possible solution to this could be Linkset: A Link Relation Type for Link Sets RFC proposal\n(a work also by Erik Wilde) but currently it’s in draft state.\nOnce published, a Linkset could group together a set of links and provide them to the client by reference.\nHowever Linksets don’t actually solve our issue because eventually the MicroTypes announcement would not\nbe solved in the HTTP level as a Linkset would have to provide a body format as well.\nAnother issue is that the server cannot specify a caching strategy for all links at once because there\nis no mechanism in HTTP which allows us to specify caching directives for specific headers only.\nAs a result, unless we used a Linkset which we can’t yet and would cancel any advantages that Lien header provides\ndue to the need of a response body,\nthe client would have to dereference all MicroTypes to figure out their caching properties.\nOn a side note, over the past few years, we have seen an explosion of link types\nused along with Lien header defined by RFC 5988.\nThe authors of Introspected REST are skeptical with this trend and feel that the Lien header should\nnot be overused.\nFor instance, having more than 5 links in the Lien header feels that something is wrong, probably too many things\nare defined in the protocol level whereas maybe they should be defined somewhere else.\nWe will let the community to decide if this approach is good for publishing MicroTypes but we would like to stress\nthe point that having a link in the HTTP level through Lien header might be better\nfor related resources that all clients would understand, which is not always the case in Introspected REST.\nThe API designer could add more MicroTypes, progressively, as the time passes and simultaneously,\nsome clients might not be interested or understand all MicroTypes of an Introspected REST.\nRequiring the client to receive all MicroType information for every data request is made\nwould probably be against the principles of Introspected REST.\n10.5. Considérations\n10.5.1 Diversifing from existing RFCs\nAlthough we have managed to apply Introspective REST to HTTP, a protocol that has been influenced so much\nby Roy’s REST model (and\nvice verca) this adaptation comes to a cost: we need to diversify from some RFCs specifications that we make use of.\nFortunately this diversification is relatively very small compared to the gains and all changes are\nbackwards compatible with existing deployed clients.\n10.5.1. HTTP OPTIONS responses are not cacheable\nFirst and most importantly, according to RFC 7231:
"},{"id":"text-126","type":"text","heading":"","plain_text":"Responses to the OPTIONS method are not cacheable.\n— RFC 7231","html":"Responses to the OPTIONS method are not cacheable.\n— RFC 7231
"},{"id":"text-127","type":"text","heading":"","plain_text":"This is the biggest breaking change to existing HTTP specs that Introspected REST applies.\nUnfortunately for a reason unknown to us, HTTP spec requires the clients to not cache responses of\nHTTP OPTIONS, essentially breaking out thinking of detached hypermedia and other metadata from plain data.\nIn practice though, adding cache headers in that HTTP method should be possible although\nlimitations by existing client implementations could exist.\nIf an API designer doesn’t want to break this part of HTTP spec then she should define the introspection\nprocess through the other suggested solutions, or come up with a new one.\nWhat is important though is that, as Introspected REST specifies, introspection process should be recognizably distinct from regular\ndata requests.\nThe authors of Introspected REST don’t see the reasoning of this constraint by HTTP spec and advise the community to investigate\nthe possibility of ignoring this limitation and proceed with HTTP OPTIONS introspection\nprocess that fits best to this architectural style.\nEventually, that would lead the IETF to completely drop it from HTTP spec.\nAlso, although the change itself could be considered as breaking because we alter a\nfunctionality that RFC 7231 specifies,\nthis alteration does not break existing clients but only the existing spec, because\nallowing clients to cache a response, which previously was not allowed, is backwards compatible.\n10.5.2. Media Type parameters must be very well defined beforehand\nAccording to RFC 6831 any Media Type parameters must be very well defined beforehand:","html":"This is the biggest breaking change to existing HTTP specs that Introspected REST applies.\nUnfortunately for a reason unknown to us, HTTP spec requires the clients to not cache responses of\nHTTP OPTIONS, essentially breaking out thinking of detached hypermedia and other metadata from plain data.\nIn practice though, adding cache headers in that HTTP method should be possible although\nlimitations by existing client implementations could exist.\nIf an API designer doesn’t want to break this part of HTTP spec then she should define the introspection\nprocess through the other suggested solutions, or come up with a new one.\nWhat is important though is that, as Introspected REST specifies, introspection process should be recognizably distinct from regular\ndata requests.\nThe authors of Introspected REST don’t see the reasoning of this constraint by HTTP spec and advise the community to investigate\nthe possibility of ignoring this limitation and proceed with HTTP OPTIONS introspection\nprocess that fits best to this architectural style.\nEventually, that would lead the IETF to completely drop it from HTTP spec.\nAlso, although the change itself could be considered as breaking because we alter a\nfunctionality that RFC 7231 specifies,\nthis alteration does not break existing clients but only the existing spec, because\nallowing clients to cache a response, which previously was not allowed, is backwards compatible.\n10.5.2. Media Type parameters must be very well defined beforehand\nAccording to RFC 6831 any Media Type parameters must be very well defined beforehand:
"},{"id":"text-128","type":"text","heading":"","plain_text":"Media types MAY elect to use one or more media type parameters, or\n some parameters may be automatically made available to the media type\n by virtue of being a subtype of a content type that defines a set of\n parameters applicable to any of its subtypes. In either case, the\n names, values, and meanings of any parameters MUST be fully specified\n when a media type is registered in the standards tree, and SHOULD be\n specified as completely as possible when media types are registered\n in the vendor or personal trees.","html":"Media types MAY elect to use one or more media type parameters, or\n some parameters may be automatically made available to the media type\n by virtue of being a subtype of a content type that defines a set of\n parameters applicable to any of its subtypes. In either case, the\n names, values, and meanings of any parameters MUST be fully specified\n when a media type is registered in the standards tree, and SHOULD be\n specified as completely as possible when media types are registered\n in the vendor or personal trees.
"},{"id":"text-129","type":"text","heading":"","plain_text":"This goes against our concept of arbitrary number of autonomous MicroTypes that can be included by a parent Media Type parameters.\nHowever, we feel that given the sparse use of Media Types parameters, such breaking change will have a very small effect.\nThe authors of Introspected REST advice the community to investigate the possibility of pushing IETF to drop this requirement,\nor extend Media Type parameters with specialized parameters that can have arbitrary names.\n10.5.3. Media Types must function as actual media formats\nAnother thing that we differentiate is that according to same spec, each Media Type’s\nprimary functionality shoud be that of being media formats.","html":"This goes against our concept of arbitrary number of autonomous MicroTypes that can be included by a parent Media Type parameters.\nHowever, we feel that given the sparse use of Media Types parameters, such breaking change will have a very small effect.\nThe authors of Introspected REST advice the community to investigate the possibility of pushing IETF to drop this requirement,\nor extend Media Type parameters with specialized parameters that can have arbitrary names.\n10.5.3. Media Types must function as actual media formats\nAnother thing that we differentiate is that according to same spec, each Media Type’s\nprimary functionality shoud be that of being media formats.
"},{"id":"text-130","type":"text","heading":"","plain_text":"Media types MUST function as actual media formats. Registration of\n things that are better thought of as a transfer encoding, as a\n charset, or as a collection of separate entities of another type, is\n not allowed. For example, although applications exist to decode the\n base64 transfer encoding [RFC2045], base64 cannot be registered as a\n media type.\nThis requirement applies regardless of the registration tree\n involved.\nRFC 6831","html":"Media types MUST function as actual media formats. Registration of\n things that are better thought of as a transfer encoding, as a\n charset, or as a collection of separate entities of another type, is\n not allowed. For example, although applications exist to decode the\n base64 transfer encoding [RFC2045], base64 cannot be registered as a\n media type.\nThis requirement applies regardless of the registration tree\n involved.\nRFC 6831
"},{"id":"text-131","type":"text","heading":"","plain_text":"In our concept of MicroTypes, the parent Media Type acts as the base media format but has\nthe possibility to be extended by small components, MicroTypes.\nThese small components, which could be different in each request, define functionalities of different parts of the API\nand such functionality is not always in the context of media formats as RFC 6831 indicates.\n10.5.4. Mixed priorities are confusing\nOne more limitation comes from our MicroTypes definition through Media Type’s parameters and is related to priorities\nbetween MicroTypes and parent Media Types.\nImagine the client is sending the following to the server:","html":"In our concept of MicroTypes, the parent Media Type acts as the base media format but has\nthe possibility to be extended by small components, MicroTypes.\nThese small components, which could be different in each request, define functionalities of different parts of the API\nand such functionality is not always in the context of media formats as RFC 6831 indicates.\n10.5.4. Mixed priorities are confusing\nOne more limitation comes from our MicroTypes definition through Media Type’s parameters and is related to priorities\nbetween MicroTypes and parent Media Types.\nImagine the client is sending the following to the server:
"},{"id":"text-132","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi, application/vnd.api2+json;","html":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi, application/vnd.api2+json;
"},{"id":"text-133","type":"text","heading":"","plain_text":"Given this header, the client sets the priorities in the following order:","html":"Given this header, the client sets the priorities in the following order:
"},{"id":"text-134","type":"text","heading":"","plain_text":"application/vnd.api+json with the following MicroTypes","html":"application/vnd.api+json with the following MicroTypes
"},{"id":"text-135","type":"text","heading":"","plain_text":"pagination=simple-spec\nquerying=graphql Ou bien querying=jsonapi","html":"pagination=simple-spec\nquerying=graphql Ou bien querying=jsonapi
"},{"id":"text-136","type":"text","heading":"","plain_text":"application/vnd.api+json with the following MicroTypes","html":"application/vnd.api+json with the following MicroTypes
"},{"id":"text-137","type":"text","heading":"","plain_text":"pagination=simple-spec\nquerying=jsonapi Ou bien querying=jsonapi","html":"pagination=simple-spec\nquerying=jsonapi Ou bien querying=jsonapi
"},{"id":"text-138","type":"text","heading":"","plain_text":"application/vnd.api2+json","html":"application/vnd.api2+json
"},{"id":"text-139","type":"text","heading":"","plain_text":"But how can the client prioritize (3) choice over (2) ?\nHaving multilevel priorities is difficult in this context and could be only solved by sending 3 options to the server,\nessentially flatting and removing the MicroTypes priority scheme that we showed and falling back to the classic Media Type negotiation:","html":"But how can the client prioritize (3) choice over (2) ?\nHaving multilevel priorities is difficult in this context and could be only solved by sending 3 options to the server,\nessentially flatting and removing the MicroTypes priority scheme that we showed and falling back to the classic Media Type negotiation:
"},{"id":"text-140","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql, application/vnd.api2+json, application/vnd.api+json; pagination=simple-spec; querying=jsonapi;","html":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql, application/vnd.api2+json, application/vnd.api+json; pagination=simple-spec; querying=jsonapi;
"},{"id":"text-141","type":"text","heading":"","plain_text":"In our experience though, negotiation in HTTP is not used that extensively (although it should): clients\nare usually prepared before hand for one Media Type (and its MicroTypes in our context).\nThus, we don’t think this will be an issue in practice, at least initially, until community embraces Introspectiveness and new standards are created\nsolving these limitations.\nThis is also not a breaking change per-se but it’s good to have it in mind and possibly reconsider it or alter it\nwhen eventually patterns for MicroTypes and parent Media Types for Introspected REST APIs are settled down.\nTo our knowledge we haven’t broken any other HTTP-related specification for Introspected REST and the broken changes that\nwe had were very minor to our understanding, all of them being backwards-compatible to existing clients.\nGiven that the whole HTTP, related protocols and implementations, since its inception have always been based on proactive\nnegotiation we think that these changes are affordable for our new model.\nEven when they are not affordable we feel that there are alternative ways to mitigate those limitations.\nBut after all, IETF, W3C and related organizations usually are not preceding implementations but instead implementations\naffect and drive these specifications through the committees.\nIf IETF sees that people are using the specifications differently than these have been defined, they should update them\nor create new ones, as long as these don’t break the existing Internet infrastructure, which they definitely do not in our case.\n10.5.2. Performance considerations\nIntrospected REST adds some performance issues related to introspection process:\nthe client needs to first do a reconnaissance request to figure out what capabilities the server supports.\nThen for each capability that is described by a MicroType, the client might possibly need to send another request\nto retrieve the metadata of that MicroType.\nThis adds much more requests than regular REST APIs which would lead to increased latency until the client fetches\nor sends the actual resource.\nHowever, according to Introspected REST, the client can cache all this information using server’s caching headers,\nwhich could be different for each MicroType.\nIn that way, Introspected REST could possibly be more performant than regular REST because the client might have to actually\nrequest metadata very sparsely compared to actual data requests and given that the data responses will be much\nsmaller than REST’s equivalent responses (which would also hold all the necessary metadata), it should lead to better performance\nà long terme.\nWe should also note that Introspected REST is not ideal for all API designs and there could be cases that REST\nbecomes a better choice than Introspected REST.\nNevertheless, we feel that for most machine-to-machine communications Introspected REST is a better choice for all the advantages\nit offers and possibly more performant than REST.\n11. An Introspected REST API prototype in the world of HTTP and JSON\nIn the following we will describe the architecture of the Introspected REST APIs through\na proposed implementation.\nThe reader though should not confuse the proposed implementation details with the actual\narchitecture style.\nThis is by no means a complete Media Type, but just an example of the potential of Introspected REST.\nThe actual MicroTypes and Media Types will be created by the community.\nFor our solution, we will use JSON,\nJSON Schemas,\nJSON super schemas,\nJSON-LD\net problem+json\neach representing a different MicroType.\nBut the reader could apply the same ideas using any message format and spec.\nOur use case will be the same as the one in section 7.1, a miniature of yet another Social App.\nGiven that Introspected REST differs only in HATEOAS part of REST, the identification of the resources devrait be kept the same, namely:","html":"In our experience though, negotiation in HTTP is not used that extensively (although it should): clients\nare usually prepared before hand for one Media Type (and its MicroTypes in our context).\nThus, we don’t think this will be an issue in practice, at least initially, until community embraces Introspectiveness and new standards are created\nsolving these limitations.\nThis is also not a breaking change per-se but it’s good to have it in mind and possibly reconsider it or alter it\nwhen eventually patterns for MicroTypes and parent Media Types for Introspected REST APIs are settled down.\nTo our knowledge we haven’t broken any other HTTP-related specification for Introspected REST and the broken changes that\nwe had were very minor to our understanding, all of them being backwards-compatible to existing clients.\nGiven that the whole HTTP, related protocols and implementations, since its inception have always been based on proactive\nnegotiation we think that these changes are affordable for our new model.\nEven when they are not affordable we feel that there are alternative ways to mitigate those limitations.\nBut after all, IETF, W3C and related organizations usually are not preceding implementations but instead implementations\naffect and drive these specifications through the committees.\nIf IETF sees that people are using the specifications differently than these have been defined, they should update them\nor create new ones, as long as these don’t break the existing Internet infrastructure, which they definitely do not in our case.\n10.5.2. Performance considerations\nIntrospected REST adds some performance issues related to introspection process:\nthe client needs to first do a reconnaissance request to figure out what capabilities the server supports.\nThen for each capability that is described by a MicroType, the client might possibly need to send another request\nto retrieve the metadata of that MicroType.\nThis adds much more requests than regular REST APIs which would lead to increased latency until the client fetches\nor sends the actual resource.\nHowever, according to Introspected REST, the client can cache all this information using server’s caching headers,\nwhich could be different for each MicroType.\nIn that way, Introspected REST could possibly be more performant than regular REST because the client might have to actually\nrequest metadata very sparsely compared to actual data requests and given that the data responses will be much\nsmaller than REST’s equivalent responses (which would also hold all the necessary metadata), it should lead to better performance\nà long terme.\nWe should also note that Introspected REST is not ideal for all API designs and there could be cases that REST\nbecomes a better choice than Introspected REST.\nNevertheless, we feel that for most machine-to-machine communications Introspected REST is a better choice for all the advantages\nit offers and possibly more performant than REST.\n11. An Introspected REST API prototype in the world of HTTP and JSON\nIn the following we will describe the architecture of the Introspected REST APIs through\na proposed implementation.\nThe reader though should not confuse the proposed implementation details with the actual\narchitecture style.\nThis is by no means a complete Media Type, but just an example of the potential of Introspected REST.\nThe actual MicroTypes and Media Types will be created by the community.\nFor our solution, we will use JSON,\nJSON Schemas,\nJSON super schemas,\nJSON-LD\net problem+json\neach representing a different MicroType.\nBut the reader could apply the same ideas using any message format and spec.\nOur use case will be the same as the one in section 7.1, a miniature of yet another Social App.\nGiven that Introspected REST differs only in HATEOAS part of REST, the identification of the resources devrait be kept the same, namely:
"},{"id":"text-142","type":"text","heading":"","plain_text":"Utilisateurs resource (/users):","html":"Utilisateurs resource (/users):
"},{"id":"text-143","type":"text","heading":"","plain_text":"List users (GET /users): Gets a collection of Utilisateur Ressources\nCreate a new user (/users): Creates a new Utilisateur with the specified attributes.","html":"List users (GET /users): Gets a collection of Utilisateur Ressources\nCreate a new user (/users): Creates a new Utilisateur with the specified attributes.
"},{"id":"text-144","type":"text","heading":"","plain_text":"Utilisateur resource (/users/id):","html":"Utilisateur resource (/users/id):
"},{"id":"text-145","type":"text","heading":"","plain_text":"Get a user (GET /users/id): Gets the attributes of the specified Utilisateur\nUpdate a user PATCH /users/id: Updates a Utilisateur with the specified attributes\nDelete a user DELETE /users/id: Updates a Utilisateur with the specified attributes","html":"Get a user (GET /users/id): Gets the attributes of the specified Utilisateur\nUpdate a user PATCH /users/id: Updates a Utilisateur with the specified attributes\nDelete a user DELETE /users/id: Updates a Utilisateur with the specified attributes
"},{"id":"text-146","type":"text","heading":"","plain_text":"Let’s assume that our parent Media Type is application/vnd.api+json.\n11.1. Isolating the actual data from metadata\nOur top priority is to offload the final response object from the metadata, like hypermedia.\nInstead, we will provide to the user only the data and possibly any runtime metadata.\nWhen the client manipulates a Utilisateur resource, the response should contain only the data:","html":"Let’s assume that our parent Media Type is application/vnd.api+json.\n11.1. Isolating the actual data from metadata\nOur top priority is to offload the final response object from the metadata, like hypermedia.\nInstead, we will provide to the user only the data and possibly any runtime metadata.\nWhen the client manipulates a Utilisateur resource, the response should contain only the data:
"},{"id":"text-147","type":"text","heading":"","plain_text":""user": \n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50","html":""user": \n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50
"},{"id":"text-148","type":"text","heading":"","plain_text":"Similarly, a Utilisateurs resource will be a collection of Utilisateur resources:","html":"Similarly, a Utilisateurs resource will be a collection of Utilisateur resources:
"},{"id":"text-149","type":"text","heading":"","plain_text":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ]","html":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ]
"},{"id":"text-150","type":"text","heading":"","plain_text":"The actual format of the data could vary regarding the root element or possibly the place of the primary id.\nSuch details will be described by the Media Type.\nWhat is important here is that the data does not contain any metadata, apart from runtime metadata,\nthat we will describe later.\n11.2 Introspection Method\nFor introspection method we will use the HTTP OPTIONS, as described in 10.4.1,\nbut with the additional description of runtime MicroTypes, which in our case do\nhave some introspective content for the client to fetch.\nThe specific semantics of this document will be described in the parent Media Type,\nbut it would look like this:","html":"The actual format of the data could vary regarding the root element or possibly the place of the primary id.\nSuch details will be described by the Media Type.\nWhat is important here is that the data does not contain any metadata, apart from runtime metadata,\nthat we will describe later.\n11.2 Introspection Method\nFor introspection method we will use the HTTP OPTIONS, as described in 10.4.1,\nbut with the additional description of runtime MicroTypes, which in our case do\nhave some introspective content for the client to fetch.\nThe specific semantics of this document will be described in the parent Media Type,\nbut it would look like this:
"},{"id":"text-151","type":"text","heading":"","plain_text":""micro-types": \n "runtime": \n "pagination": \n "url": "/api/users/1?microtype=pagination",\n "method": "OPTIONS",\n "content-type": "application/simple-pagination+json",\n "priority": "1.0"\n ,\n "errors": \n "url": "/api/users/1?microtype=errors",\n "method": "OPTIONS",\n "content-type": "application/simple-errors+json",\n "priority": "1.0"\n \n ,\n "introspective": \n "json-schema": \n "url": "/api/users/1?microtype=json-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json",\n "priority": "0.8"\n ,\n "json-hyper-schema": \n "url": "/api/users/1?microtype=json-hyper-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json",\n "priority": "0.8"\n ,\n "json-ld": \n "url": "/api/users/1?microtype=json-ld",\n "method": "OPTIONS",\n "content-type": "application/ld+json",\n "priority": "0.5"\n ,\n "simple-description": \n "url": "/api/users/1?microtype=simple-description",\n "method": "OPTIONS",\n "content-type": "application/json",\n "priority": "0.2"\n \n \n ,\n "documentation": \n "url": "/documentation#user",\n "method": "OBTENIR",\n "content-type": "text/html"","html":""micro-types": \n "runtime": \n "pagination": \n "url": "/api/users/1?microtype=pagination",\n "method": "OPTIONS",\n "content-type": "application/simple-pagination+json",\n "priority": "1.0"\n ,\n "errors": \n "url": "/api/users/1?microtype=errors",\n "method": "OPTIONS",\n "content-type": "application/simple-errors+json",\n "priority": "1.0"\n \n ,\n "introspective": \n "json-schema": \n "url": "/api/users/1?microtype=json-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json",\n "priority": "0.8"\n ,\n "json-hyper-schema": \n "url": "/api/users/1?microtype=json-hyper-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json",\n "priority": "0.8"\n ,\n "json-ld": \n "url": "/api/users/1?microtype=json-ld",\n "method": "OPTIONS",\n "content-type": "application/ld+json",\n "priority": "0.5"\n ,\n "simple-description": \n "url": "/api/users/1?microtype=simple-description",\n "method": "OPTIONS",\n "content-type": "application/json",\n "priority": "0.2"\n \n \n ,\n "documentation": \n "url": "/documentation#user",\n "method": "OBTENIR",\n "content-type": "text/html"
"},{"id":"text-152","type":"text","heading":"","plain_text":"Each entry describes the url which the client can access it, the HTTP method\nthe client should use along with the Media Type of the expected response.\nFinalement, le priorité number specifies the preceding order of each MicroType\nin case a functionality is described by one or more MicroTypes.\nNote that the Media Type of the introspective content will be described\nby the MicroType the client tries to access.\nAs a result, if a client doesn’t recognize a MicroType, it wouldn’t try to access\nit anyway.\n11.2. Runtime Metadata\nIt goes without saying that when a client requests a collection of resources,\nit expects some kind of pagination with it.\nFor pagination MicroType we have a number of different options.\nOne option is to use the Lien header and define the links there, in a representation-agnostic way.\nBut given that our application is intended to powerful clients that would also parse the JSON body\nwe wouldn’t gain much, possibly we would make things even more complex for them.\nAnother possibility, with some inspiration from JSONAPI, is to use the premier, dernier, prev et suivant spécifier\nthe first, last, previous and next page respectively.","html":"Each entry describes the url which the client can access it, the HTTP method\nthe client should use along with the Media Type of the expected response.\nFinalement, le priorité number specifies the preceding order of each MicroType\nin case a functionality is described by one or more MicroTypes.\nNote that the Media Type of the introspective content will be described\nby the MicroType the client tries to access.\nAs a result, if a client doesn’t recognize a MicroType, it wouldn’t try to access\nit anyway.\n11.2. Runtime Metadata\nIt goes without saying that when a client requests a collection of resources,\nit expects some kind of pagination with it.\nFor pagination MicroType we have a number of different options.\nOne option is to use the Lien header and define the links there, in a representation-agnostic way.\nBut given that our application is intended to powerful clients that would also parse the JSON body\nwe wouldn’t gain much, possibly we would make things even more complex for them.\nAnother possibility, with some inspiration from JSONAPI, is to use the premier, dernier, prev et suivant spécifier\nthe first, last, previous and next page respectively.
"},{"id":"text-153","type":"text","heading":"","plain_text":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ],\n "meta":\n "self":"/api/users?page=2&per_page=10&offset=0",\n "first":"/api/users?page=1&per_page=10&offset=0",\n "prev":"/api/users?page=1&per_page=10&offset=0",\n "next":"/api/users?page=2&per_page=10&offset=0",\n "last":"/api/users?page=9&per_page=10&offset=0"","html":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ],\n "meta":\n "self":"/api/users?page=2&per_page=10&offset=0",\n "first":"/api/users?page=1&per_page=10&offset=0",\n "prev":"/api/users?page=1&per_page=10&offset=0",\n "next":"/api/users?page=2&per_page=10&offset=0",\n "last":"/api/users?page=9&per_page=10&offset=0"
"},{"id":"text-154","type":"text","heading":"","plain_text":"A different approach is to just specify\nla page, per_page et décalage to the client and also provide a URI template to\nuse with those values to access any page.","html":"A different approach is to just specify\nla page, per_page et décalage to the client and also provide a URI template to\nuse with those values to access any page.
"},{"id":"text-155","type":"text","heading":"","plain_text":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ],\n "meta": \n "page": 2,\n "per_page": dix,\n "offset": 0","html":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ],\n "meta": \n "page": 2,\n "per_page": dix,\n "offset": 0
"},{"id":"text-156","type":"text","heading":"","plain_text":"We could provide the URI template when introspecting the pagination MicroType:","html":"We could provide the URI template when introspecting the pagination MicroType:
"},{"id":"text-157","type":"text","heading":"","plain_text":""link": "/api/resource?page, per_page, offset"","html":""link": "/api/resource?page, per_page, offset"
"},{"id":"text-158","type":"text","heading":"","plain_text":"Of course, the MicroType spec would specify how the client should parse and determine\nthe pagination links from this introspective content.\nIn that way, we don’t treat the clients as stupid but smart enough to understand\nwhat they need to do on their part to get what they want.\nWhich is the best solution? It depends, and that’s why we should embrace MicroTypes.\nle Lien header-based solution is representation-agnostic and could benefit some clients\nthat don’t deal much with the content but in practice such clients are very rare, especially in our use case.\nThe second solution would limit the client application developer if she wanted to have a link\nof a specific page, while the last solution would limit the API designer to avoid\nhaving the number of total pages in the response, because it could be a huge cost to the database level.\nIn any case, Introspected REST doesn’t restrict us to specify two or more alternative MicroTypes for the same API\nfonctionnalité, like pagination.\n11.2.2 The Errors MicroType\nWhen the API is supposed to return an unexpected response to the user, like a 4xx or 5xx error,\nthe response will have a different structure than the resource that the client requested.\nUsually the semantics of an error respond are defined in the API’s Media Type but we will use the newly-published RFC 7807 (Problem Details for HTTP APIs),\nwhich defines the problem+json Media Type for JSON HTTP APIs.\nTo give an example how the response will seem when following this RFC,\nimagine that when updating a User object, the application developer might wrongly send an invalid birth_date.\nThen the application should respond with the following structure:","html":"Of course, the MicroType spec would specify how the client should parse and determine\nthe pagination links from this introspective content.\nIn that way, we don’t treat the clients as stupid but smart enough to understand\nwhat they need to do on their part to get what they want.\nWhich is the best solution? It depends, and that’s why we should embrace MicroTypes.\nle Lien header-based solution is representation-agnostic and could benefit some clients\nthat don’t deal much with the content but in practice such clients are very rare, especially in our use case.\nThe second solution would limit the client application developer if she wanted to have a link\nof a specific page, while the last solution would limit the API designer to avoid\nhaving the number of total pages in the response, because it could be a huge cost to the database level.\nIn any case, Introspected REST doesn’t restrict us to specify two or more alternative MicroTypes for the same API\nfonctionnalité, like pagination.\n11.2.2 The Errors MicroType\nWhen the API is supposed to return an unexpected response to the user, like a 4xx or 5xx error,\nthe response will have a different structure than the resource that the client requested.\nUsually the semantics of an error respond are defined in the API’s Media Type but we will use the newly-published RFC 7807 (Problem Details for HTTP APIs),\nwhich defines the problem+json Media Type for JSON HTTP APIs.\nTo give an example how the response will seem when following this RFC,\nimagine that when updating a User object, the application developer might wrongly send an invalid birth_date.\nThen the application should respond with the following structure:
"},{"id":"text-159","type":"text","heading":"","plain_text":""Titre": "The birthdate has an invalid format.",\n "details": "The birthdate must be in the format of 1985-04-12T23:20:50.52Z.",\n "status": 422","html":""Titre": "The birthdate has an invalid format.",\n "details": "The birthdate must be in the format of 1985-04-12T23:20:50.52Z.",\n "status": 422
"},{"id":"text-160","type":"text","heading":"","plain_text":"If you inspect the spec you will notice that the spec limits us by omitting specifying a way to associate an error message with a specific resource attribute.\nAs a result, we can only specify the falsy attribute in the title or details attribute of the error object, which are human-targeted,\nand thus informing only the end user and not the client.\nWe could add extension members, as the spec suggests, to customize the error object in our needs but the final response object wouldn’t be\nself-descriptive, unless we customly extended it.\nThe good thing though is that normally such errors should be caught on the client-side by the introspected MicroTypes for the resource structure,\nwhich in our use case are the schema validations from the JSON Schema MicroType.\nThe error object could be used for more advanced errors, like the following:","html":"If you inspect the spec you will notice that the spec limits us by omitting specifying a way to associate an error message with a specific resource attribute.\nAs a result, we can only specify the falsy attribute in the title or details attribute of the error object, which are human-targeted,\nand thus informing only the end user and not the client.\nWe could add extension members, as the spec suggests, to customize the error object in our needs but the final response object wouldn’t be\nself-descriptive, unless we customly extended it.\nThe good thing though is that normally such errors should be caught on the client-side by the introspected MicroTypes for the resource structure,\nwhich in our use case are the schema validations from the JSON Schema MicroType.\nThe error object could be used for more advanced errors, like the following:
"},{"id":"text-161","type":"text","heading":"","plain_text":""Titre": "Transaction failed",\n "details": "The remaining amount of virtual coins in your account is not enough for this purchase",\n "status": 403","html":""Titre": "Transaction failed",\n "details": "The remaining amount of virtual coins in your account is not enough for this purchase",\n "status": 403
"},{"id":"text-162","type":"text","heading":"","plain_text":"Another thing that we should take care is the fact that this RFC requires returning a different Media Type than the one used by the API.\nIn theory the API’s Media Type explain how the errors work using the same semantics as defined in problem+json RFC but the RFC\nsuggests using application/problem+json for Media Type.","html":"Another thing that we should take care is the fact that this RFC requires returning a different Media Type than the one used by the API.\nIn theory the API’s Media Type explain how the errors work using the same semantics as defined in problem+json RFC but the RFC\nsuggests using application/problem+json for Media Type.
"},{"id":"text-163","type":"text","heading":"","plain_text":"The data model for problem details is a JSON [RFC7159] object; quand\nformatted as a JSON document, it uses the “application/problem+json”\nmedia type.\n— RFC 7807\nHowever in order for this to work the client needs to negotiate it and accept this Media Type,\notherwise we have a gap in the client-server communication.\nThe client can’t be asking for the API’s Media Type and unexpectedly receive the application/problem+json\nMedia Type.","html":"The data model for problem details is a JSON [RFC7159] object; quand\nformatted as a JSON document, it uses the “application/problem+json”\nmedia type.\n— RFC 7807\nHowever in order for this to work the client needs to negotiate it and accept this Media Type,\notherwise we have a gap in the client-server communication.\nThe client can’t be asking for the API’s Media Type and unexpectedly receive the application/problem+json\nMedia Type.
"},{"id":"text-164","type":"text","heading":"","plain_text":"In HTTP that would be achieved using the Acceptez header, which could look like that:","html":"In HTTP that would be achieved using the Acceptez header, which could look like that:
"},{"id":"text-165","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json, application/problem+json","html":"Accept: application/vnd.api+json, application/problem+json
"},{"id":"text-166","type":"text","heading":"","plain_text":"But that reminds us the concept of (runtime) MicroTypes, right?\nEven the negotiation looks very similar.\nTo that extend, creating a wrapper MicroType shim around this Media Type, that other API designers\ncan also use, should be effortless.\nTo take one step further, given that such error information is crucial for the user to understand why her action is not advancing,\nwe feel that the client should be able to négocier the errors MicroType, that is, the information and structure of the\nreturned errors object.\nSome clients might need the most basic error information and use only the HTTP status code, other clients might\nbe interested in as much possible information available in order to show it to the user.\nFor instance, the client might show preference to another problems Media Type before falling back to problem+jsoncomme\nseen in the following Accept header example:","html":"But that reminds us the concept of (runtime) MicroTypes, right?\nEven the negotiation looks very similar.\nTo that extend, creating a wrapper MicroType shim around this Media Type, that other API designers\ncan also use, should be effortless.\nTo take one step further, given that such error information is crucial for the user to understand why her action is not advancing,\nwe feel that the client should be able to négocier the errors MicroType, that is, the information and structure of the\nreturned errors object.\nSome clients might need the most basic error information and use only the HTTP status code, other clients might\nbe interested in as much possible information available in order to show it to the user.\nFor instance, the client might show preference to another problems Media Type before falling back to problem+jsoncomme\nseen in the following Accept header example:
"},{"id":"text-167","type":"text","heading":"","plain_text":"Accept: application/vnd.api+json, errors=problem/extensive+json, errors=problem+json;","html":"Accept: application/vnd.api+json, errors=problem/extensive+json, errors=problem+json;
"},{"id":"text-168","type":"text","heading":"","plain_text":"11.3. Introspective Metadata\nWe will describe our APIs capabilities by mixing together different MicroTypes targeted each one for a specific capability\nof our API, following the Single Responsibility Principle.\nThe client will be able to retrieve the information of each metadata MicroType by introspecting the resource.\n11.3.1. Structural metadata\nOne of the most important things for a client to know is the expected structure of the request/response resource object\nalong with information on the data types.\nFor that we will use JSON Schemas, a powerful spec that enables you to describe and validate your JSON data.\nGiven that this specification has been published using the RFC method and taking into account its popularity,\nit is very probable that there est\nan implementation for that MicroType for the client’s environment.\nAlso, a cool side effect of having the structure definition of the resource as a MicroType available through resource’s introspection,\nis that the client can use this information to first validate the object before sending it over the wire to the server.\n11.3.1.1. User resource","html":"11.3. Introspective Metadata\nWe will describe our APIs capabilities by mixing together different MicroTypes targeted each one for a specific capability\nof our API, following the Single Responsibility Principle.\nThe client will be able to retrieve the information of each metadata MicroType by introspecting the resource.\n11.3.1. Structural metadata\nOne of the most important things for a client to know is the expected structure of the request/response resource object\nalong with information on the data types.\nFor that we will use JSON Schemas, a powerful spec that enables you to describe and validate your JSON data.\nGiven that this specification has been published using the RFC method and taking into account its popularity,\nit is very probable that there est\nan implementation for that MicroType for the client’s environment.\nAlso, a cool side effect of having the structure definition of the resource as a MicroType available through resource’s introspection,\nis that the client can use this information to first validate the object before sending it over the wire to the server.\n11.3.1.1. User resource
"},{"id":"text-169","type":"text","heading":"","plain_text":"{\n "$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/user.json",\n "Propriétés":{\n "user":\n "type":"objet",\n "Propriétés":\n "id":\n "maxLength":64,\n "type":"chaîne"\n ,\n "email":\n "maxLength":255,\n "type":"chaîne",\n "format":"email"\n ,\n "name":\n "maxLength":255,\n "type":[[[["null", "chaîne"]\n ,\n "birth_date":\n "type":"chaîne",\n "pattern":"^[0-9]4-[0-9]2-[0-9]2$"\n ,\n "created_at":\n "maxLength":255,\n "type":"chaîne",\n "format":"date-time"\n ,\n "microposts_count":\n "type":"entier"\n \n ,\n "Champs obligatoires":[[[[\n "id",\n "email",\n "name",\n "birth_date",\n "created_at",\n "microposts_count"\n ]\n \n },\n "Champs obligatoires":[[[[\n "user"\n ],\n "type":"objet"\n}","html":"{\n "$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/user.json",\n "Propriétés":{\n "user":\n "type":"objet",\n "Propriétés":\n "id":\n "maxLength":64,\n "type":"chaîne"\n ,\n "email":\n "maxLength":255,\n "type":"chaîne",\n "format":"email"\n ,\n "name":\n "maxLength":255,\n "type":[[[["null", "chaîne"]\n ,\n "birth_date":\n "type":"chaîne",\n "pattern":"^[0-9]4-[0-9]2-[0-9]2$"\n ,\n "created_at":\n "maxLength":255,\n "type":"chaîne",\n "format":"date-time"\n ,\n "microposts_count":\n "type":"entier"\n \n ,\n "Champs obligatoires":[[[[\n "id",\n "email",\n "name",\n "birth_date",\n "created_at",\n "microposts_count"\n ]\n \n },\n "Champs obligatoires":[[[[\n "user"\n ],\n "type":"objet"\n}
"},{"id":"text-170","type":"text","heading":"","plain_text":"11.3.1.2. Users resource\nNote that the Users resource is just a collection of User object and as a result\nit references the User schema.","html":"11.3.1.2. Users resource\nNote that the Users resource is just a collection of User object and as a result\nit references the User schema.
"},{"id":"text-171","type":"text","heading":"","plain_text":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/users.json",\n "Propriétés":\n "users":\n "type": "array",\n "$href": "https://example.com/user.json#/properties/user"\n ,\n "meta": \n "type":"objet",\n "page": \n "type": "entier",\n "default": 0,\n "le minimum": 0,\n "$ref": "#/definitions/extra"\n ,\n "per_page": \n "type": "entier",\n "le minimum": 1,\n "maximum": 100,\n "default": 50\n ,\n "offset": \n "type": "entier",\n "le minimum": 0,\n "default": 0\n ,\n "Champs obligatoires":[[[[\n "page",\n "per_page",\n "offset"\n ],\n \n ,\n "Champs obligatoires":[[[[\n "users",\n "meta"\n ],\n "type":"objet"","html":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/users.json",\n "Propriétés":\n "users":\n "type": "array",\n "$href": "https://example.com/user.json#/properties/user"\n ,\n "meta": \n "type":"objet",\n "page": \n "type": "entier",\n "default": 0,\n "le minimum": 0,\n "$ref": "#/definitions/extra"\n ,\n "per_page": \n "type": "entier",\n "le minimum": 1,\n "maximum": 100,\n "default": 50\n ,\n "offset": \n "type": "entier",\n "le minimum": 0,\n "default": 0\n ,\n "Champs obligatoires":[[[[\n "page",\n "per_page",\n "offset"\n ],\n \n ,\n "Champs obligatoires":[[[[\n "users",\n "meta"\n ],\n "type":"objet"
"},{"id":"text-172","type":"text","heading":"","plain_text":"11.3.1.3. Request Response inconsistency\nAlthough here we have the same object semantics for request and response object, in theory these could be different.\nIf that’s the case, we should denote each object in the response parented under\ndistinct JSON attributes (like accepte/produit ou accepte/résultats).\n11.3.2. Hypermedia metadata\nFor the Hypermedia part we will use JSON Hyper Schemas.\nSpecifically we will use the draft V4 of JSON Hyper Schemas as the\nnext versions (V5, V6) are targeted to hypermedia APIs that\nare HTML-equivalents. For instance, there is no way we can define a méthode attribute, restricting us to OBTENIR et POSTER\ndepending whether there is a body to send or not.\nIn the Introspected REST terminology, V5 and V6\nprovide hypermedia semantics only for forms and not actions.\nResource schemas defined in the previous section are referenced by the following Hyper Schemas, in order to avoid\nduplication of our metadata.\nSuch functionality would have to be described by both MicroTypes.\n11.3.2.1. User resource","html":"11.3.1.3. Request Response inconsistency\nAlthough here we have the same object semantics for request and response object, in theory these could be different.\nIf that’s the case, we should denote each object in the response parented under\ndistinct JSON attributes (like accepte/produit ou accepte/résultats).\n11.3.2. Hypermedia metadata\nFor the Hypermedia part we will use JSON Hyper Schemas.\nSpecifically we will use the draft V4 of JSON Hyper Schemas as the\nnext versions (V5, V6) are targeted to hypermedia APIs that\nare HTML-equivalents. For instance, there is no way we can define a méthode attribute, restricting us to OBTENIR et POSTER\ndepending whether there is a body to send or not.\nIn the Introspected REST terminology, V5 and V6\nprovide hypermedia semantics only for forms and not actions.\nResource schemas defined in the previous section are referenced by the following Hyper Schemas, in order to avoid\nduplication of our metadata.\nSuch functionality would have to be described by both MicroTypes.\n11.3.2.1. User resource
"},{"id":"text-173","type":"text","heading":"","plain_text":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/user-links.json",\n "Propriétés":\n "$href": "https://example.com/user.json#/properties"\n ,\n "links": [[[[\n \n "rel": "microposts",\n "href": "/microposts?user=userId&page=page&per_page=per_page&offset=offset",\n "hrefSchema": \n "allOf": [[[[\n \n "$ref": "https://example.com/users.json#/properties/meta"\n ,\n \n "$ref": "https://example.com/users.json#/properties/user/id"\n ,\n ]\n \n ,\n \n "rel": "update-user",\n "href": "/users",\n "method": "PATCH",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n ,\n \n "rel": "delete-user",\n "href": "/users",\n "method": "DELETE",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n \n ]","html":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/user-links.json",\n "Propriétés":\n "$href": "https://example.com/user.json#/properties"\n ,\n "links": [[[[\n \n "rel": "microposts",\n "href": "/microposts?user=userId&page=page&per_page=per_page&offset=offset",\n "hrefSchema": \n "allOf": [[[[\n \n "$ref": "https://example.com/users.json#/properties/meta"\n ,\n \n "$ref": "https://example.com/users.json#/properties/user/id"\n ,\n ]\n \n ,\n \n "rel": "update-user",\n "href": "/users",\n "method": "PATCH",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n ,\n \n "rel": "delete-user",\n "href": "/users",\n "method": "DELETE",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n \n ]
"},{"id":"text-174","type":"text","heading":"","plain_text":"11.3.2.2. Users resource","html":"11.3.2.2. Users resource
"},{"id":"text-175","type":"text","heading":"","plain_text":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/users-links.json",\n "Propriétés":\n "$href": "https://example.com/users.json#/properties"\n ,\n "links": [[[[\n \n "rel": "self",\n "href": "/users?page=page&per_page=per_page&offset=offset",\n "hrefSchema": \n "$ref": "https://example.com/users.json#/properties/meta"\n \n ,\n \n "rel": "create-user",\n "href": "/users",\n "method": "POST",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n \n ]","html":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/users-links.json",\n "Propriétés":\n "$href": "https://example.com/users.json#/properties"\n ,\n "links": [[[[\n \n "rel": "self",\n "href": "/users?page=page&per_page=per_page&offset=offset",\n "hrefSchema": \n "$ref": "https://example.com/users.json#/properties/meta"\n \n ,\n \n "rel": "create-user",\n "href": "/users",\n "method": "POST",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n \n ]
"},{"id":"text-176","type":"text","heading":"","plain_text":"Notice that we also define here the pagination, by referencing parts of the user’s méta objet.\nOur strategy is duplicate common functionality in MicroTypes, wherever we can, in order to help\nour clients. Possibly not all clients will be programmed for all our MicroTypes, especially if we\nrelease them progressively.\n11.3.4. Descriptions metadata\nFor human-targeted information, we could use a custom MicroType that describes each attribute of the response object.\nNotez que this information must not be required to parse and understand the API but to use the API data on our application domain.\nFor instance, understanding that when updating the email attribute an email is triggered to inform the user for the change,\nis not part of the API client responsibility but it’s vital for the application developer to to know what to expect from it.","html":"Notice that we also define here the pagination, by referencing parts of the user’s méta objet.\nOur strategy is duplicate common functionality in MicroTypes, wherever we can, in order to help\nour clients. Possibly not all clients will be programmed for all our MicroTypes, especially if we\nrelease them progressively.\n11.3.4. Descriptions metadata\nFor human-targeted information, we could use a custom MicroType that describes each attribute of the response object.\nNotez que this information must not be required to parse and understand the API but to use the API data on our application domain.\nFor instance, understanding that when updating the email attribute an email is triggered to inform the user for the change,\nis not part of the API client responsibility but it’s vital for the application developer to to know what to expect from it.
"},{"id":"text-177","type":"text","heading":"","plain_text":""user": \n "id": \n "Titre": "The identifier of the resource.",\n "la description": [[[[\n "This identifier should not be exposed to the user, to avoid any confusions."\n ]\n ,\n "email": \n "Titre": "The primary email of the user's account",\n "la description": [[[[\n "The email is used for any transactional email.",\n "Also, the same email is used when user authenticates to the system.",\n "Please note that whenever you update the email, user receives an automated email describing the change"\n ]\n ,\n "name": \n "Titre": "The user's full name (first and last name concatenated)",\n "la description": [[[[\n "This field could be empty or null.",\n "If so, the application should show the email instead for the user's name."\n ]\n ,\n "birth_date": \n "Titre": "The date of birth of the user",\n "la description": []\n ,\n "microposts_count": \n "Titre": "The number of published microposts the user has.",\n "la description": [[[[\n "Please note that due to caching this number could have a small delay to reflect the actual number",\n "The application should either inform the user about that or make sure it manually updates the microposts counter after publishing/deleting a micropost after publishing/deleting a micropost."\n ]","html":""user": \n "id": \n "Titre": "The identifier of the resource.",\n "la description": [[[[\n "This identifier should not be exposed to the user, to avoid any confusions."\n ]\n ,\n "email": \n "Titre": "The primary email of the user's account",\n "la description": [[[[\n "The email is used for any transactional email.",\n "Also, the same email is used when user authenticates to the system.",\n "Please note that whenever you update the email, user receives an automated email describing the change"\n ]\n ,\n "name": \n "Titre": "The user's full name (first and last name concatenated)",\n "la description": [[[[\n "This field could be empty or null.",\n "If so, the application should show the email instead for the user's name."\n ]\n ,\n "birth_date": \n "Titre": "The date of birth of the user",\n "la description": []\n ,\n "microposts_count": \n "Titre": "The number of published microposts the user has.",\n "la description": [[[[\n "Please note that due to caching this number could have a small delay to reflect the actual number",\n "The application should either inform the user about that or make sure it manually updates the microposts counter after publishing/deleting a micropost after publishing/deleting a micropost."\n ]
"},{"id":"text-178","type":"text","heading":"","plain_text":"This metadata will be used for the documentation generation, as we will see in section 11.7.\n11.3.5. The case of a non-compatible spec for introspection: Linked Data metadata using JSON-LD\nFor denoting the semantic meaning of each attribute of our resources we will employ JSON-LD.\nIt should be noted that JSON-LD spec was developed with the goal to require as little effort as possible from developers\nto transform their existing JSON to JSON-LD but also to not require breaking changes to your\nexisting API, which makes it backwards compatible with any current deployed API.\nThis conflicts with our design of introspection because having contexts without the data would break the spec.\nAs a result we have the following 2 options.\n11.3.5.1. Extending spec by creating a Shim MicroType\nOur first option is to create a wrapper shim MicroType that defines how the spec should work\nfor the clients to parse and understand the data, with the least possible changes.\nA naive shim, that we show here, would output the context information in the introspected process.\nThen the client should match this information in combination with the runtime data.\n11.3.3.1. User resource","html":"This metadata will be used for the documentation generation, as we will see in section 11.7.\n11.3.5. The case of a non-compatible spec for introspection: Linked Data metadata using JSON-LD\nFor denoting the semantic meaning of each attribute of our resources we will employ JSON-LD.\nIt should be noted that JSON-LD spec was developed with the goal to require as little effort as possible from developers\nto transform their existing JSON to JSON-LD but also to not require breaking changes to your\nexisting API, which makes it backwards compatible with any current deployed API.\nThis conflicts with our design of introspection because having contexts without the data would break the spec.\nAs a result we have the following 2 options.\n11.3.5.1. Extending spec by creating a Shim MicroType\nOur first option is to create a wrapper shim MicroType that defines how the spec should work\nfor the clients to parse and understand the data, with the least possible changes.\nA naive shim, that we show here, would output the context information in the introspected process.\nThen the client should match this information in combination with the runtime data.\n11.3.3.1. User resource
"},{"id":"text-179","type":"text","heading":"","plain_text":""@context": \n "@vocab": "https://schema.org/",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul","html":""@context": \n "@vocab": "https://schema.org/",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul
"},{"id":"text-180","type":"text","heading":"","plain_text":"11.3.3.2. Users resource","html":"11.3.3.2. Users resource
"},{"id":"text-181","type":"text","heading":"","plain_text":""@context": \n "@vocab": "https://schema.org/",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n ,\n "@graph": [[[[\n \n "@type": "La personne"\n \n ]","html":""@context": \n "@vocab": "https://schema.org/",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n ,\n "@graph": [[[[\n \n "@type": "La personne"\n \n ]
"},{"id":"text-182","type":"text","heading":"","plain_text":"11.3.5.2. Considering it as runtime metadata\nOur second option is to exploit the IATEOAS principles regarding runtime metadata\nand append them inside the response by considering them as object-specific runtime metadata.\nHowever, we feel that such decision should be taken only if nothing else is possible,\ngiven that in Introspected REST data and metadata should be distinctively separated.\n11.7. Automating the documentation generation\nThe documentation of our API should be a dedicated page under the API’s URL namespace (i.e. /api),\nby returning a regular web page, targeted to humans and not machines.\nThe technical details is out of the scope of this prototype example but we\ncan’t stress enough that the generated documentation should mostly use information from MicroTypes available for the machines,\nprogrammatically wrapped in a human-friendly format.\n12.1. GraphQL\nGraphQL is a data query language that was created by Facebook and released to the public\nin 2015.\nThe specification of the query language is not tied to the protocol used\nunderneath or the message format, although HTTP in combination with JSON is usually used.\nWhat is different about GraphQL is that it makes the client’s requirements and performance\nas a top priority, regardless of the internal implementation of the data layer in the server.\nAs a result, front-end engineers tend to love it due to its expressiveness that\nusually is not found in REST APIs.\nFor instance, retrieving a Utilisateur object with a subset of it’s attributes, along\nwith some microposts ordered by creation date, is very easy, given that the server\nimplementation support those filters:","html":"11.3.5.2. Considering it as runtime metadata\nOur second option is to exploit the IATEOAS principles regarding runtime metadata\nand append them inside the response by considering them as object-specific runtime metadata.\nHowever, we feel that such decision should be taken only if nothing else is possible,\ngiven that in Introspected REST data and metadata should be distinctively separated.\n11.7. Automating the documentation generation\nThe documentation of our API should be a dedicated page under the API’s URL namespace (i.e. /api),\nby returning a regular web page, targeted to humans and not machines.\nThe technical details is out of the scope of this prototype example but we\ncan’t stress enough that the generated documentation should mostly use information from MicroTypes available for the machines,\nprogrammatically wrapped in a human-friendly format.\n12.1. GraphQL\nGraphQL is a data query language that was created by Facebook and released to the public\nin 2015.\nThe specification of the query language is not tied to the protocol used\nunderneath or the message format, although HTTP in combination with JSON is usually used.\nWhat is different about GraphQL is that it makes the client’s requirements and performance\nas a top priority, regardless of the internal implementation of the data layer in the server.\nAs a result, front-end engineers tend to love it due to its expressiveness that\nusually is not found in REST APIs.\nFor instance, retrieving a Utilisateur object with a subset of it’s attributes, along\nwith some microposts ordered by creation date, is very easy, given that the server\nimplementation support those filters:
"},{"id":"text-183","type":"text","heading":"","plain_text":"utilisateur(identifiant: "1") \n prénom\n email\n birth_date\n microposts (limite: dix, orderBy: created_at)\n Titre\n \n \n}","html":"utilisateur(identifiant: "1") \n prénom\n email\n birth_date\n microposts (limite: dix, orderBy: created_at)\n Titre\n \n \n}
"},{"id":"text-184","type":"text","heading":"","plain_text":"The query not only specifies what the client wants to retrieve but also it specifies\nthe structure the response should have.\nAlso, GraphQL supports an introspection process that clients can use in order to figure\nout the available fields of each resource along with other useful information, like\ndata types, the available operations those resource support (mutations in GraphQL terminology) etc.\nGraphQL solves common issues in networked APIs in a radical, unique way.\nFacebook engineers figured out that instead of trying to adapt\nexisting Internet infrastructure and protocols to their needs, they designed\na query language that solves their problems and use HTTP as a dumb pipe to do the hard work of\ncommunicating both queries and data.\nIn terms of REST principles, GraphQL responses are both evolvable and self-descriptive, as GraphQL’s\nintrospection is very powerful allowing the clients to learn anything that is needed\nabout the resources.\nHowever, we feel that GraphQL does have some costs and it’s not a solution that any\nbusiness can apply.\nFirst, GraphQL doesn’t play well with the existing HTTP infrastructure.\nFor instance, most GraphQL implementations, use a single endpoint with the same\nHTTP method, POSTER, for the client-server communication.\nAs a result, the specification cannot take advantage of existing HTTP protocols\nand mechanisms but instead has to re-invent the wheel on some of them, like caching.\nAlso, adding GraphQL to an existing service has huge costs.\nAlthough there are libraries for most languages and frameworks that facilitate the development of\nGraphQL API, this is not always the case.\nBut apart from that, the server engineer must take full responsibility for supporting all\nkind of queries the client might need and at the same time these queries need to be efficient and scalable.\nWhen we can know in advance what are the limits of a query, we are able to optimize for it,\nhowever, with GraphQL, a client can send any query using any of the all the possible resources and structure them\nin a way that for the server is random.\nIn such cases, it’s impractical to optimize beforehand and solving scaling issue becomes\na real challenge that possibly only companies with huge amount of resources can really afford.\nAnd again, as with existing Media Types design, GraphQL creates a closed silo in our API and differentiating from the existing\nspec is nearly impossible.\nFor instance, if we need to support an additional data type, it’s impossible\nbecause we are dependent to the existing libraries and creating our own GraphQL library would require too much time.\nBut even if that was solved, a possible modification in the current spec would probably break most existing clients.\nWe feel that a MicroType-based architecture is more powerful than a specification that, although powerful,\nlimits the users to its semantics.\nThe fact that REST API designers haven’t treated very well front-end\nengineers in the past, in combination with the complexity a modern\nREST API could have, has given a lot of space to GraphQL to rise as one of the most prominent\nAPI designs.\nAlthough GraphQL is a great asset to have it around, we don’t think that it’s practical for\nall API cases, but instead it mostly suits best big companies that can afford the costs.\nThe API designer must balance the trade off between the cost of development and the\nclient’s affordances.\nWith Introspected REST and a number of powerful MicroTypes it is possible to replicate the existing GraphQL\nspecification and even leverage existing HTTP infrastructure.\nIn fact, we feel that Introspected REST is far more powerful than GraphQL:\nnot only it gives you the ability to balance the costs of implementation and client performance,\nbut also it can support multiple, different, querying specs for different classes of clients,\nall these by leveraging the existing HTTP infrastructure.\n12.2. Linked Data and Semantic Web\nLinked data and semantic web has been trying to solve the problem of mutual understanding\nbetween machines many years now.\nUsing a pre-defined vocabulary, machines can determine the type of a resource, like if\nit’s a person, an employee, an athlete or\neven the types of each attribute of a resource, like a name, an email etc.\nIt is a step close to have self-descriptive APIs that machines can understand and process.\nFor instance, using JSON-LD as we saw earlier, we can specify all attributes of a Utilisateur resource:","html":"The query not only specifies what the client wants to retrieve but also it specifies\nthe structure the response should have.\nAlso, GraphQL supports an introspection process that clients can use in order to figure\nout the available fields of each resource along with other useful information, like\ndata types, the available operations those resource support (mutations in GraphQL terminology) etc.\nGraphQL solves common issues in networked APIs in a radical, unique way.\nFacebook engineers figured out that instead of trying to adapt\nexisting Internet infrastructure and protocols to their needs, they designed\na query language that solves their problems and use HTTP as a dumb pipe to do the hard work of\ncommunicating both queries and data.\nIn terms of REST principles, GraphQL responses are both evolvable and self-descriptive, as GraphQL’s\nintrospection is very powerful allowing the clients to learn anything that is needed\nabout the resources.\nHowever, we feel that GraphQL does have some costs and it’s not a solution that any\nbusiness can apply.\nFirst, GraphQL doesn’t play well with the existing HTTP infrastructure.\nFor instance, most GraphQL implementations, use a single endpoint with the same\nHTTP method, POSTER, for the client-server communication.\nAs a result, the specification cannot take advantage of existing HTTP protocols\nand mechanisms but instead has to re-invent the wheel on some of them, like caching.\nAlso, adding GraphQL to an existing service has huge costs.\nAlthough there are libraries for most languages and frameworks that facilitate the development of\nGraphQL API, this is not always the case.\nBut apart from that, the server engineer must take full responsibility for supporting all\nkind of queries the client might need and at the same time these queries need to be efficient and scalable.\nWhen we can know in advance what are the limits of a query, we are able to optimize for it,\nhowever, with GraphQL, a client can send any query using any of the all the possible resources and structure them\nin a way that for the server is random.\nIn such cases, it’s impractical to optimize beforehand and solving scaling issue becomes\na real challenge that possibly only companies with huge amount of resources can really afford.\nAnd again, as with existing Media Types design, GraphQL creates a closed silo in our API and differentiating from the existing\nspec is nearly impossible.\nFor instance, if we need to support an additional data type, it’s impossible\nbecause we are dependent to the existing libraries and creating our own GraphQL library would require too much time.\nBut even if that was solved, a possible modification in the current spec would probably break most existing clients.\nWe feel that a MicroType-based architecture is more powerful than a specification that, although powerful,\nlimits the users to its semantics.\nThe fact that REST API designers haven’t treated very well front-end\nengineers in the past, in combination with the complexity a modern\nREST API could have, has given a lot of space to GraphQL to rise as one of the most prominent\nAPI designs.\nAlthough GraphQL is a great asset to have it around, we don’t think that it’s practical for\nall API cases, but instead it mostly suits best big companies that can afford the costs.\nThe API designer must balance the trade off between the cost of development and the\nclient’s affordances.\nWith Introspected REST and a number of powerful MicroTypes it is possible to replicate the existing GraphQL\nspecification and even leverage existing HTTP infrastructure.\nIn fact, we feel that Introspected REST is far more powerful than GraphQL:\nnot only it gives you the ability to balance the costs of implementation and client performance,\nbut also it can support multiple, different, querying specs for different classes of clients,\nall these by leveraging the existing HTTP infrastructure.\n12.2. Linked Data and Semantic Web\nLinked data and semantic web has been trying to solve the problem of mutual understanding\nbetween machines many years now.\nUsing a pre-defined vocabulary, machines can determine the type of a resource, like if\nit’s a person, an employee, an athlete or\neven the types of each attribute of a resource, like a name, an email etc.\nIt is a step close to have self-descriptive APIs that machines can understand and process.\nFor instance, using JSON-LD as we saw earlier, we can specify all attributes of a Utilisateur resource:
"},{"id":"text-185","type":"text","heading":"","plain_text":""user": \n "@context": \n "@vocab": "https://schema.org/",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n ,\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50","html":""user": \n "@context": \n "@vocab": "https://schema.org/",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n ,\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50
"},{"id":"text-186","type":"text","heading":"","plain_text":"Moreover, modern specifications like JSON-LD allow us to omit\nthe definitions from the response’s data and instead provide only a link to\na publicly accessible directory that a machine can déréférence,\nsimilarly to the introspection method of Introspected REST.\nThe resource ony needs to have the vocab attribute inside JSON-LD’s le contexte.","html":"Moreover, modern specifications like JSON-LD allow us to omit\nthe definitions from the response’s data and instead provide only a link to\na publicly accessible directory that a machine can déréférence,\nsimilarly to the introspection method of Introspected REST.\nThe resource ony needs to have the vocab attribute inside JSON-LD’s le contexte.
"},{"id":"text-187","type":"text","heading":"","plain_text":""user": \n "@context": \n "@vocab": "https://example.com/my-custom-schema/"\n ,\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50","html":""user": \n "@context": \n "@vocab": "https://example.com/my-custom-schema/"\n ,\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50
"},{"id":"text-188","type":"text","heading":"","plain_text":"The idea of semantic web can be found even in real life.\nIn an example taken by Donald Norman, and\noften quoted by Mike Amundsen’s talks,\nin real life when we see a door, we know instantly how it opens because we have associated\nthe design of the door with its opening mechanism:\nif a door has a bar across it then we push while if there is a little handle in the door then we pull.\nWhile semantic web allow us to associate resources in the web with entities that hold\nmetadata and have specific properties, in Introspected REST we ask the door itself how its mechanism works:\nusing the door’s metadata we can learn how to open any door and eventually we can even\nopen doors whose opening mechanism we have never seen before.\nIn any case, in Introspected REST we embrace semantic web by employing the necessary MicroTypes\nand we don’t really feel that this work is related to Introspected REST in a competing sense\nbut instead, both concepts could complement each other.\nIn fact, we feel that using linked data is just great and API designers should employ it more often.\n12.2.1 Hydra\nTo that extend, Markus Lantaler developed Hydra, which not only allows us to associate\ncommon resources and attributes with their representation but also RESTful hypermedia\nconcepts on them, like actions (called operations), links, status codes etc.\nSo again in our use case, we can specify some actions using Hydra:","html":"The idea of semantic web can be found even in real life.\nIn an example taken by Donald Norman, and\noften quoted by Mike Amundsen’s talks,\nin real life when we see a door, we know instantly how it opens because we have associated\nthe design of the door with its opening mechanism:\nif a door has a bar across it then we push while if there is a little handle in the door then we pull.\nWhile semantic web allow us to associate resources in the web with entities that hold\nmetadata and have specific properties, in Introspected REST we ask the door itself how its mechanism works:\nusing the door’s metadata we can learn how to open any door and eventually we can even\nopen doors whose opening mechanism we have never seen before.\nIn any case, in Introspected REST we embrace semantic web by employing the necessary MicroTypes\nand we don’t really feel that this work is related to Introspected REST in a competing sense\nbut instead, both concepts could complement each other.\nIn fact, we feel that using linked data is just great and API designers should employ it more often.\n12.2.1 Hydra\nTo that extend, Markus Lantaler developed Hydra, which not only allows us to associate\ncommon resources and attributes with their representation but also RESTful hypermedia\nconcepts on them, like actions (called operations), links, status codes etc.\nSo again in our use case, we can specify some actions using Hydra:
"},{"id":"text-189","type":"text","heading":"","plain_text":""@context": [[[[\n "http://www.w3.org/ns/hydra/core",\n \n "@vocab": "https://example.com/my-custom-user-vocab",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n \n ],\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50,\n "operation": \n "@type": "UpdateUser",\n "method": "PATCH",\n "expects": \n "@id": "https://example.com/my-custom-user-vocab",\n "supportedProperty": [[[[\n \n "@type": "email",\n "property": "email",\n "Champs obligatoires": faux\n ,\n \n "@type": "name",\n "property": "name",\n "Champs obligatoires": faux\n ,\n \n "@type": "birthDate",\n "property": "birth_date",\n "Champs obligatoires": faux\n \n ]","html":""@context": [[[[\n "http://www.w3.org/ns/hydra/core",\n \n "@vocab": "https://example.com/my-custom-user-vocab",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n \n ],\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50,\n "operation": \n "@type": "UpdateUser",\n "method": "PATCH",\n "expects": \n "@id": "https://example.com/my-custom-user-vocab",\n "supportedProperty": [[[[\n \n "@type": "email",\n "property": "email",\n "Champs obligatoires": faux\n ,\n \n "@type": "name",\n "property": "name",\n "Champs obligatoires": faux\n ,\n \n "@type": "birthDate",\n "property": "birth_date",\n "Champs obligatoires": faux\n \n ]
"},{"id":"text-190","type":"text","heading":"","plain_text":"Again, Hydra’s-specific content, like operations, can become dereferencable thus\nmaking response’s load much smaller, although this is not a requirement as in\nIntrospected REST.\nAlthough we support initiatives that allow API designers to serve metadata on the side,\nlike Hydra does with dereferencable content, we can’t miss the fact that Hydra\nhas become a very complex specification and still it’s type system is a weak one.\nWe firmly believe that MicroTypes for actions (Hydra’s equivalent to operations)\nwill be much more powerful than hydra’s semantics of Champs obligatoires, en écriture, lisible,\nand soon an API designer will be able to choose one MicroType from the same class of\nMicroTypes, like data types, that fits best for her.\nSpecifications that try to define everything in one place, like Hydra does, limit\nthe API designers a lot and eventually such specs\ndeliver an mediocre set of choices to choose from.\nIn any case, we feel that Hydra spec is one of the few API specs that significantly\ndiffers from the conventional API specs and can provide almost completely self descriptive\nles réponses, an unfortunately rare key property of modern APIs.\n12.3. The ‘profile’ Link Relation Type\nSimilar to the profile media type parameter\nthat Toby A. Inkster had proposed in 2009, Erik Wilde suggested a profiling mechanism\nof the underlying Media Type through the HTTP Link header, that was later\npublished as RFC 6906.","html":"Again, Hydra’s-specific content, like operations, can become dereferencable thus\nmaking response’s load much smaller, although this is not a requirement as in\nIntrospected REST.\nAlthough we support initiatives that allow API designers to serve metadata on the side,\nlike Hydra does with dereferencable content, we can’t miss the fact that Hydra\nhas become a very complex specification and still it’s type system is a weak one.\nWe firmly believe that MicroTypes for actions (Hydra’s equivalent to operations)\nwill be much more powerful than hydra’s semantics of Champs obligatoires, en écriture, lisible,\nand soon an API designer will be able to choose one MicroType from the same class of\nMicroTypes, like data types, that fits best for her.\nSpecifications that try to define everything in one place, like Hydra does, limit\nthe API designers a lot and eventually such specs\ndeliver an mediocre set of choices to choose from.\nIn any case, we feel that Hydra spec is one of the few API specs that significantly\ndiffers from the conventional API specs and can provide almost completely self descriptive\nles réponses, an unfortunately rare key property of modern APIs.\n12.3. The ‘profile’ Link Relation Type\nSimilar to the profile media type parameter\nthat Toby A. Inkster had proposed in 2009, Erik Wilde suggested a profiling mechanism\nof the underlying Media Type through the HTTP Link header, that was later\npublished as RFC 6906.
"},{"id":"text-191","type":"text","heading":"","plain_text":"A profile is defined not to alter the\n semantics of the resource representation itself, but to allow clients\n to learn about additional semantics (constraints, conventions,\n extensions) that are associated with the resource representation, in\n addition to those defined by the media type and possibly other\n mechanisms.\n— RFC 6906","html":"A profile is defined not to alter the\n semantics of the resource representation itself, but to allow clients\n to learn about additional semantics (constraints, conventions,\n extensions) that are associated with the resource representation, in\n addition to those defined by the media type and possibly other\n mechanisms.\n— RFC 6906
"},{"id":"text-192","type":"text","heading":"","plain_text":"Essentially, the profile parameter, given that the client understands it, would define Additionnel semantics of\nthe response’s representation that are not defined through the Media Type used.\nThe information for the additional semantics would be found in all responses regardless the client but only\nthe “smarter” clients would be able to parse, understand and use this information whereas the rest would just ignore it.\nThis link relation type is similar to our work of MicroTypes but unfortunately fails to advocate towards reusable profiles.","html":"Essentially, the profile parameter, given that the client understands it, would define Additionnel semantics of\nthe response’s representation that are not defined through the Media Type used.\nThe information for the additional semantics would be found in all responses regardless the client but only\nthe “smarter” clients would be able to parse, understand and use this information whereas the rest would just ignore it.\nThis link relation type is similar to our work of MicroTypes but unfortunately fails to advocate towards reusable profiles.
"},{"id":"text-193","type":"text","heading":"","plain_text":"While this specification\n associates profiles with resource representations, creators and users\n of profiles MAY define and manage them in a way that allows them to\n be used across media types; thus, they could be associated with a\n resource, independent of their representations (i.e., using the same\n profile URI for different media types). However, such a design is\n outside of the scope of this specification, and clients SHOULD treat\n profiles as being associated with a resource representation.\n— RFC 6906","html":"While this specification\n associates profiles with resource representations, creators and users\n of profiles MAY define and manage them in a way that allows them to\n be used across media types; thus, they could be associated with a\n resource, independent of their representations (i.e., using the same\n profile URI for different media types). However, such a design is\n outside of the scope of this specification, and clients SHOULD treat\n profiles as being associated with a resource representation.\n— RFC 6906
"},{"id":"text-194","type":"text","heading":"","plain_text":"By having profiles attached to specific Media Types results in much less adoptability and flexibility and fails to signal the\nactual practicability of such architecture.\nHowever, if profiles take the conceptual form of independent MicroTypes, then the clients can negotiate for those and eventually choose\nthe one that fits best.\nAlthough the negotiation part is skipped from the RFC, we feel that such works are towards the right direction that will allow us\nto build evolvable, self-described APIs.\n12.4. JSON Home\nNote that JSON Home is still in a draft state.\nJSON home is a draft specification\nthat defines a “home document” format for non-browser HTTP clients to first request in order to discover\nthe server’s capabilities that it support.\nSpecifically, the document specifies semantics to describe the API itself (like author, documentation link etc)\nalong with its resources.\nFor each resource, the document can provide a link for the client to access it directly (instead of\nfiguring out the link using REST state transitions) and more information, mostly hints, like\npermitted methods, media types etc.\nIt should be noted that JSON Home it’s one of the few specifications along with RFC 7807 (Problem Details for HTTP APIs)\nand possibly Linksets that\nbecause of their semantics and specifications, they slide away from Roy’s REST model and\nacknowledge the distinction between\nbrowser-based clients that are driven by real humans, and non-browser, machine based-clients and suggests\nthat the latter should be treated differently.\nAs the draft notes the benefits of using such a home document are multifold:","html":"By having profiles attached to specific Media Types results in much less adoptability and flexibility and fails to signal the\nactual practicability of such architecture.\nHowever, if profiles take the conceptual form of independent MicroTypes, then the clients can negotiate for those and eventually choose\nthe one that fits best.\nAlthough the negotiation part is skipped from the RFC, we feel that such works are towards the right direction that will allow us\nto build evolvable, self-described APIs.\n12.4. JSON Home\nNote that JSON Home is still in a draft state.\nJSON home is a draft specification\nthat defines a “home document” format for non-browser HTTP clients to first request in order to discover\nthe server’s capabilities that it support.\nSpecifically, the document specifies semantics to describe the API itself (like author, documentation link etc)\nalong with its resources.\nFor each resource, the document can provide a link for the client to access it directly (instead of\nfiguring out the link using REST state transitions) and more information, mostly hints, like\npermitted methods, media types etc.\nIt should be noted that JSON Home it’s one of the few specifications along with RFC 7807 (Problem Details for HTTP APIs)\nand possibly Linksets that\nbecause of their semantics and specifications, they slide away from Roy’s REST model and\nacknowledge the distinction between\nbrowser-based clients that are driven by real humans, and non-browser, machine based-clients and suggests\nthat the latter should be treated differently.\nAs the draft notes the benefits of using such a home document are multifold:
"},{"id":"text-195","type":"text","heading":"","plain_text":"o Extensibility – Because new server capabilities can be expressed\n as link relations, new features can be layered in without\n introducing a new API version; clients will discover them in the\n home document. This promotes loose coupling between clients and\n les serveurs.\no Evolvability – Likewise, interfaces can change gradually by\n introducing a new link relation and/or format while still\n supporting the old ones.\no Customisation – Home documents can be tailored for the client,\n allowing different classes of service or different client\n permissions to be exposed naturally.\no Flexible deployment – Since URLs aren’t baked into documentation,\n the server can choose what URLs to use for a given service.\no API mixing – Likewise, more than one API can be deployed on a\n given server, without fear of collisions.\n— Home Documents for HTTP APIs, draft 06","html":"o Extensibility – Because new server capabilities can be expressed\n as link relations, new features can be layered in without\n introducing a new API version; clients will discover them in the\n home document. This promotes loose coupling between clients and\n les serveurs.\no Evolvability – Likewise, interfaces can change gradually by\n introducing a new link relation and/or format while still\n supporting the old ones.\no Customisation – Home documents can be tailored for the client,\n allowing different classes of service or different client\n permissions to be exposed naturally.\no Flexible deployment – Since URLs aren’t baked into documentation,\n the server can choose what URLs to use for a given service.\no API mixing – Likewise, more than one API can be deployed on a\n given server, without fear of collisions.\n— Home Documents for HTTP APIs, draft 06
"},{"id":"text-196","type":"text","heading":"","plain_text":"Although we can instantly see the benefits of such structure, we believe that a specification like JSON Home\nis very weak. Specifically, it is tied to JSON message format which, although very popular, could possibly be\ninappropriate in some use cases.\nInstead, a better idea would be to define the necessary attributes and semantics that a Home document\nshould provide and then let the API designer to choose if these will be implemented in JSON, XML or binary format.\nSuch architecture would be more robust and would give more options to an API designer.\nSecondly, the document resource hints are very abstract and generic that probably are not sufficient\nfor the client to parse them without some documentation.\nOur work makes use of MicroTypes that allows the API designer to offload such information\nto more specific formats, possible duplicated in multiple specs to support as many as possible\nclients, but also to let the clients select the most appropriate MicroType(s) for them.\nWe firmly believe that a MicroType-based architecture is much more powerful than a simple,\nsemantically identical for all APIs, JSON-specific, home document.\nHowever we can’t neglect the fact that influencing engineers are finally recognizing the\ndissimilarity of browser-based, driven by humans clients and machine-based clients.\nIn fact, carving our infrastructure for machine-based clients to be similar with human-driven clients we\nunderestimate their capabilities: machines can be much more powerful and smart than humans.\n12.5. RESTful API Description Languages\nOver the past years, there has been a trend on creating API documentation through specialized tools, like OpenAPI specification (ex. Swagger).\nAs we have already noted, in a REST API documentation, in the sense of offline contracts,\nshouldn’t even exist and thus such approach is fundamentally wrong.\nBy giving so much weight on the documentation but at the same time treating it as something different, separated from the code\nleads to inconsistencies between the actual API and the API description.\nThose tools have been improved so much lately that now allow us to write the documentation and let them generate\nthe basis of our code, depending on our language/framework, which could fix the inconsistencies issues.\nUnfortunately though, such approach leads to an RPC design instead of a hypermedia-based system.\nWe believe that API designers are limited by marrying these tools.\nThe tools themselves have limitations,\nbut also, having tools that aim to provide all-in-one to the API designer is against our philosophy: tools should do one thing and do it well.\n12.6. API directories\nAnother trend for APIs is to register them in an online service, called API dictionary and possible push there the API documentation as well.\nWe feel that this is not a very helpful structure. APIs should be discoverable by themselves without using centralized services.\nThe API’s conceptual root url should provide everything that is needed, and using already published protocols\nlike WebFinger, which builds upon Well-Known Uniform Resource Identifiers RFC\nand can give API information for client bootstraping.\n13. Conclusion","html":"Although we can instantly see the benefits of such structure, we believe that a specification like JSON Home\nis very weak. Specifically, it is tied to JSON message format which, although very popular, could possibly be\ninappropriate in some use cases.\nInstead, a better idea would be to define the necessary attributes and semantics that a Home document\nshould provide and then let the API designer to choose if these will be implemented in JSON, XML or binary format.\nSuch architecture would be more robust and would give more options to an API designer.\nSecondly, the document resource hints are very abstract and generic that probably are not sufficient\nfor the client to parse them without some documentation.\nOur work makes use of MicroTypes that allows the API designer to offload such information\nto more specific formats, possible duplicated in multiple specs to support as many as possible\nclients, but also to let the clients select the most appropriate MicroType(s) for them.\nWe firmly believe that a MicroType-based architecture is much more powerful than a simple,\nsemantically identical for all APIs, JSON-specific, home document.\nHowever we can’t neglect the fact that influencing engineers are finally recognizing the\ndissimilarity of browser-based, driven by humans clients and machine-based clients.\nIn fact, carving our infrastructure for machine-based clients to be similar with human-driven clients we\nunderestimate their capabilities: machines can be much more powerful and smart than humans.\n12.5. RESTful API Description Languages\nOver the past years, there has been a trend on creating API documentation through specialized tools, like OpenAPI specification (ex. Swagger).\nAs we have already noted, in a REST API documentation, in the sense of offline contracts,\nshouldn’t even exist and thus such approach is fundamentally wrong.\nBy giving so much weight on the documentation but at the same time treating it as something different, separated from the code\nleads to inconsistencies between the actual API and the API description.\nThose tools have been improved so much lately that now allow us to write the documentation and let them generate\nthe basis of our code, depending on our language/framework, which could fix the inconsistencies issues.\nUnfortunately though, such approach leads to an RPC design instead of a hypermedia-based system.\nWe believe that API designers are limited by marrying these tools.\nThe tools themselves have limitations,\nbut also, having tools that aim to provide all-in-one to the API designer is against our philosophy: tools should do one thing and do it well.\n12.6. API directories\nAnother trend for APIs is to register them in an online service, called API dictionary and possible push there the API documentation as well.\nWe feel that this is not a very helpful structure. APIs should be discoverable by themselves without using centralized services.\nThe API’s conceptual root url should provide everything that is needed, and using already published protocols\nlike WebFinger, which builds upon Well-Known Uniform Resource Identifiers RFC\nand can give API information for client bootstraping.\n13. Conclusion
"},{"id":"text-197","type":"text","heading":"","plain_text":"The best software architecture “knows” what changes often and makes that easy.\n— Paul Clements","html":"The best software architecture “knows” what changes often and makes that easy.\n— Paul Clements
"},{"id":"text-198","type":"text","heading":"","plain_text":"Is it the API spec designers to blame for creating non self-descriptive REST specifications or did they make a deliberate choice\nto avoid fully support the HATEOAS constraint of REST and instead delegate such information to documentation?\nIn the research of a fully REST API, we determined that REST is complex and\ninflexible.\nMoreover, its adaptation in HTTP goes through the mechanism of Media Types\nwhich specifies the whole API vocabulary in a sole place\nwhile HATEOAS need to bear the brunt of communicating to the client the available\ncapabilities of the server, based on Media Type’s vocabulary,\nfor each resource.\nThe result is very complex API responses that tangle together hypermedia with data making development a real\nchallenge for both the client and the server.\nOur new model, Introspected REST, which solves most of REST issues, steps on Roy’s initial model\nbut takes a different path regarding hypermedia. It requires the server to deliver only\ndata when a resource is requested, stripping out any HATEOAS-related information and instead deliver\nthe hypermedia on the side whenever a client needs it.\nHowever, Introspected REST goes beyond conventional hypermedia by supporting more classes of metadata, other\nthan hypermedia, through our concept of MicroTypes which act as small reusable components of API\nfonctionnalité.\nMicroTypes are not intended to be used only for allowing the client to derive the application state\nat runtime. They also make the clients smarter by allowing them to take an active role\nin the client-server communication\nwhile enabling them to provide essential feedback to the application layer.\nWe firmly believe that Introspected REST is the key to evolvable services of the future that are accessed by unmanned clients\nwith a lifespan of decades.\nOur model allows the API designers to fine-tune the flexibility and extensibility of the API to their needs,\neven progressively or asymmetrically for different classes of clients.\nChoosing between REST or GraphQL won’t be necessary as our model can support both styles simultaneously,\nusing multiple sets of MicroTypes.","html":"Is it the API spec designers to blame for creating non self-descriptive REST specifications or did they make a deliberate choice\nto avoid fully support the HATEOAS constraint of REST and instead delegate such information to documentation?\nIn the research of a fully REST API, we determined that REST is complex and\ninflexible.\nMoreover, its adaptation in HTTP goes through the mechanism of Media Types\nwhich specifies the whole API vocabulary in a sole place\nwhile HATEOAS need to bear the brunt of communicating to the client the available\ncapabilities of the server, based on Media Type’s vocabulary,\nfor each resource.\nThe result is very complex API responses that tangle together hypermedia with data making development a real\nchallenge for both the client and the server.\nOur new model, Introspected REST, which solves most of REST issues, steps on Roy’s initial model\nbut takes a different path regarding hypermedia. It requires the server to deliver only\ndata when a resource is requested, stripping out any HATEOAS-related information and instead deliver\nthe hypermedia on the side whenever a client needs it.\nHowever, Introspected REST goes beyond conventional hypermedia by supporting more classes of metadata, other\nthan hypermedia, through our concept of MicroTypes which act as small reusable components of API\nfonctionnalité.\nMicroTypes are not intended to be used only for allowing the client to derive the application state\nat runtime. They also make the clients smarter by allowing them to take an active role\nin the client-server communication\nwhile enabling them to provide essential feedback to the application layer.\nWe firmly believe that Introspected REST is the key to evolvable services of the future that are accessed by unmanned clients\nwith a lifespan of decades.\nOur model allows the API designers to fine-tune the flexibility and extensibility of the API to their needs,\neven progressively or asymmetrically for different classes of clients.\nChoosing between REST or GraphQL won’t be necessary as our model can support both styles simultaneously,\nusing multiple sets of MicroTypes.
"},{"id":"text-199","type":"text","heading":"","plain_text":"Click to rate this post!\n \n [Total: 0 Average: 0]","html":"Click to rate this post!\n \n [Total: 0 Average: 0]
"}],"sections":[{"id":"text-1","heading":"Text","content":"Dans ce manifeste, nous allons donner une définition précise de ce que REST est, selon Roy,\net voir la majorité des API et spécifications API (JSONAPI, HAL, etc.) ne pas suivre ce modèle.\nNous verrons quels problèmes une API RESTful apporte et pourquoi les concepteurs d’API sont constamment\nen évitant de l’utiliser, mais en proposant des solutions à mi-parcours ou un repli sur des solutions alternatives.\ndes modèles tels que RPC sur HTTP ou, récemment, GraphQL.\nEnsuite, nous proposerons un nouveau modèle, REST Introspected,\nqui résout les problèmes créés par REST et permet la conception d’API évolutives,\nde manière beaucoup plus simple que REST conventionnel.\nDans le cadre de ce manifeste, nous présenterons également le concept de MicroTypes,\npetits modules réutilisables qui composent un type de support et facilitent son évolution\net extensibilité de notre nouveau modèle.\nPour la mise en œuvre de notre nouveau modèle en HTTP, il faudra remonter dans le temps,\napprofondir les RFC existantes et découvrir des concepts oubliés, tels que le contenu réactif\nparamètres de négociation et de type de média, afin de plier le réseau Internet existant\nl'infrastructure, qui a été principalement influencée par les concepts REST, et a appliqué avec succès notre nouveau modèle.\n1. Définitions\nTout d’abord, quelques définitions que nous utiliserons dans le texte:"},{"id":"text-2","heading":"Text","content":"DU REPOS, Reposant: Le modèle que Roy a défini dans sa thèse (avec son API de post de blog doit être piloté par hypertexte).\nLe reste: API qui suivent tous les modèles de pièces REST, sauf HATEOAS dans lequel ils supportent principalement des liens (spécifications telles que JSONAPI, HAL, etc.)\nAgité: API ayant une API JSON simple sans aucun lien (suit un modèle REST autre que HATEOAS)\nREST Introspecté: Les API qui suivent la définition du modèle que nous fournissons dans cette manifeste"},{"id":"text-3","heading":"Text","content":"Nous utiliserons le terme API et API en réseau de manière interchangeable.\n2. Introduction\nREST défini par Roy était un travail magnifique, très en avance sur son temps\nce qui nous a pris de nombreuses années pour comprendre quelles sont ses capacités.\nCependant, presque 20 ans plus tard, le modèle REST montre son âge. C’est inflexible,\ndifficile à mettre en œuvre, difficile à tester, avec des problèmes de performance et de mise en œuvre.\nMais le plus important, toute implémentation du modèle REST est très complexe.\nMaintenant, on pourrait dire que la plupart des API ne sont pas conçues pour durer des décennies et peut-être\nC’est la raison pour laquelle ce modèle n’a pas été très adopté.\nLe premier est vrai, mais même si le dernier est aussi vrai, cela pourrait-il signifier que ce modèle est\nne convient pas aux API à court terme?\nNous croyons fermement que REST est bien meilleur que toute API qui ne suit pas DU REPOS des principes\n(comme les API RESTly), même pour les API à court terme.\nLes services en réseau ont des caractéristiques très particulières que, jusqu'à présent, seuls REST et GraphQL les ont entièrement pris en charge.\nIl est essentiel de pouvoir faire évoluer notre API sans casser les clients.\nImaginez le scénario suivant: nous avons créé un réseau social en ligne et une application iOS qui communique avec l'API sur notre backend.\nMaintenant, imaginez qu’après une réunion d’entreprise, notre PDG ait besoin que nous apportions des modifications minimes mais importantes à la page d’inscription: demandez à l’utilisateur\npour remplir son âge, un champ du formulaire d'inscription que nous n'avions pas auparavant.\nCela signifie essentiellement, en termes d'API, ajouter un champ supplémentaire dans l'objet accepté et obliger le client à le renseigner.\npar l'utilisateur avant de l'envoyer.\nSi notre API est RESTly et non REST, cela signifie que nous devons corriger le code côté iOS, le tester et envoyer une nouvelle application iOS à Apple Store.\nIl faut environ une semaine à Apple pour examiner notre application. Si, pour une raison quelconque, notre application n’est pas rejetée pendant le processus de révision, notre\npetit changement prendra des mesures au moins une semaine plus tard après la demande.\nSi notre API était REST, cela signifierait un simple changement dans la réponse du serveur, indiquant quels champs sont requis pour soumettre le formulaire.\nLe changement serait déployé 10 minutes plus tard.\nRoy note dans sa thèse:"},{"id":"text-4","heading":"Text","content":"Un système qui se veut aussi durable que le Web doit être préparé au changement\n– Roy Fielding"},{"id":"text-5","heading":"Text","content":"Dans le monde des startups et des entreprises axées sur l'argent, les éléments suivants seront plus attrayants:"},{"id":"text-6","heading":"Text","content":"Si vous souhaitez agir rapidement, vous devez créer une API axée sur le changement en premier."},{"id":"text-7","heading":"Text","content":"Une API qui peut changer l'état du client sans avoir à changer ce dernier.\nÉtant donné que, comment pouvons-nous avoir un modèle plus simple que REST, tout en tirant la même, sinon plus, fonctionnalité de\nDU REPOS?\nComme nous le montrerons, Introspected REST est un style architectural API qui résout ce problème.\nUn style architectural n’est pas une implémentation et ce n’est pas non plus une spécification.\nComme le note Roy:"},{"id":"text-8","heading":"Text","content":"Un style architectural est un ensemble coordonné de contraintes architecturales qui limite\n les rôles / caractéristiques des éléments architecturaux et les relations autorisées entre ceux-ci\n éléments de toute architecture conforme à ce style.\n– Roy Fielding"},{"id":"text-9","heading":"Text","content":"Introspected REST est basé sur le modèle initial de Roy, mais élimine le besoin de runtime HATEOAS.\nAu lieu de cela, le client dérive l'état à la demande, en utilisant l'introspection, en récupérant les métadonnées nécessaires.\nqui sont d'intérêt.\nFinalement, cela apporte les mêmes avantages que le modèle de Roy, tout en étant beaucoup plus simple,\nbeaucoup plus souple et compatible avec toutes les API RESTly ou RESTless.\nMais parlons d’abord des services en réseau.\n3. Services en réseau et API\nAujourd'hui, JSON est devenu si populaire que les développeurs oublient presque qu'il existe un tas de\nprotocoles en dessous.\nLes développeurs oublient également que JSON n'est qu'une spécification au niveau du message, comme XML.\nCe n’est pas le seul et ce n’est certainement pas le meilleur que nous puissions utiliser.\nNéanmoins, c’est simple et la simplicité est une vertu.\nBien que le modèle OSI soit le modèle conceptuel que nous utilisons pour décrire les réseaux informatiques,\navec TCP / IP suivant 5 couches d’abstraction OSI sur 7, dans notre cas, nous en ferons une description plus spécifique à l’API.\nLorsque nous souhaitons demander une ressource à une API hypermédia en réseau, nous grossièrement\navoir les niveaux suivants:\n3.1. Niveau d'application\nAu niveau de l’application, le client commence la négociation du contenu (ou la sélection du contenu), généralement en demandant\npour un seul type de support.\nUn type de support fournit des informations sur la structure du contenu et le format du message utilisé dans les données qu'il décrit.\ncomme décrit par la RFC 2046.\nDans le protocole HTTP, la négociation du contenu est réalisée par un client à l'aide de l'en-tête Accept qui indique les types de support qu'il\npeut comprendre, dans un ordre de préférence.\nEnsuite, le serveur répond avec un type de support proposé par le client dans l'en-tête Content-Type.\napplication / json est un type de support qui indique que le format de données de la demande\nla représentation est au format de données JSON.\nPlus précisément, le type de ce type de support est application tandis que le sous-type est JSON.\nJSON lui-même n'est pas un type de support mais un format de message.\nLes types de support peuvent également être un peu plus complexes: application / vnd.api + json, le type de support de la spécification JSONAPI, signifie (à peu près) que"},{"id":"text-10","heading":"Text","content":"le type principal est application\nle sous-type est vnd.api lequel grossièrement dénote le nom du type de média\nla structure sous-jacente suit la sémantique JSON"},{"id":"text-11","heading":"Text","content":"En théorie, la sémantique des spécifications JSONAPI pourrait également être appliquée en utilisant XML comme format de données (comme dans le cas de HAL),\nou même YAML, mais en pratique, nous avons tendance à l'oublier et nous traitons tous les types de supports comme uniques et non composites.\nCependant, il convient également de noter que le Les types de média et la négociation de contenu en général sont\nnon limité à HTTP seulement.\nBien que HTTP soit l’un des protocoles de réseau d’applications les plus populaires à l’heure actuelle, la même logique pourrait être appliquée.\ndans d'autres protocoles (principalement textuels) tels que SIP, CoAP, QUIC, etc.\nEn résumé, la sémantique au niveau de l'application est définie par le type de média demandé et ne doit pas être étroitement couplée à la sémantique du\nniveau du message (comme JSON) ou le niveau de protocole sous-jacent (comme HTTP).\n3.2. Niveau du message\nAu niveau du message, nous trouvons le format utilisé pour la représentation réelle.\nAujourd’hui, nous avons presque mélangé le niveau de message avec JSON, mais dans la pratique,\nformats pourraient être utilisés avec succès: XML, YAML, TOML pour en nommer quelques-uns.\nLe format de message utilisé est généralement décrit par le suffixe du type de support.\n3.3. Niveau de protocole\nAu niveau du protocole, les demandes sont généralement envoyées à l'aide du protocole HTTP.\nAprès tout, de nos jours, la majeure partie du développement se fait sur le Web et\nHTTP est le seul protocole officiellement pris en charge par les navigateurs.\nNéanmoins, il existe également d'autres protocoles similaires sans état.\nQUIC est un protocole alternatif HTTP ciblé pour une faible latence et utilise UDP.\nsous.\nCoAP est ciblé dans l'IdO et utilise également UDP en dessous (la pile TCP / IP complète est assez lourde pour les périphériques à contraintes).\nSIP est également un protocole textuel avec la même sémantique que HTTP et est utilisé en VoIP.\n3.4. Niveau réseau\nEnfin, au niveau du réseau, le navigateur (ou tout autre client autre que le navigateur) envoie la requête en réseau.\ndans l'un des TCP, UDP, etc.\nLe protocole réel dépend du protocole utilisé au niveau du protocole.\n4. Modèle REST de Roy\nRoy a mis au point le modèle REST afin de résoudre les problèmes liés aux propriétés uniques des services en réseau.\npendant la petite enfance d'Internet.\nLorsque nous développons une application qui sera déployée dans un environnement réseau et que d’autres services en réseau devraient y accéder,\nnous devons réfléchir à son évolutivité:\nsi nous devons ajouter, supprimer ou modifier les fonctionnalités de cette application\nnous ne pouvons pas nous attendre à ce que les services à l'autre bout parlent avec notre application d'être mis à jour par des humains.\nDe tels problèmes résultant des particularités des réseaux, tels que la découverte et l’évolutivité, doivent être résolus en utilisant\ncommunication machine à machine.\nLe modèle REST qui résout de tels problèmes est un style architectural qui n'est lié à aucune spécification, protocole ou format de la\nles niveaux susmentionnés."},{"id":"text-12","heading":"Text","content":"une API RESTful n'est qu'un site Web pour les utilisateurs dont le vocabulaire est limité (interaction machine à machine)\n– Roy Fielding"},{"id":"text-13","heading":"Text","content":"Quand Roy parle de REST, il mentionne 5 propriétés cruciales de DU REPOS modèle:\n4.1. Les méthodes d'accès ont la même sémantique pour toutes les ressources"},{"id":"text-14","heading":"Text","content":"induit visible, évolutif, disponible via des systèmes multicouches, des caches partageables et cachables"},{"id":"text-15","heading":"Text","content":"L’absence de cohérence dans l’accès impliquerait que nous ne fournissions pas une interface générique mais\nnous avons des interfaces spécifiques aux ressources ou même aux objets.\nEn fait, une interface commune est l’une des parties les plus cruciales de REST: sans une interface uniforme commune\nil serait impossible de dériver REST."},{"id":"text-16","heading":"Text","content":"La caractéristique centrale qui distingue le style architectural REST des autres\nstyles basés sur le réseau est l'accent mis sur une interface uniforme entre les composants.\nEn appliquant le principe de génie logiciel général à l’interface composant,\nl'architecture globale du système est simplifiée et la visibilité des interactions est améliorée.\nLes implémentations sont découplées des services qu’elles fournissent, ce qui encourage les opérateurs indépendants.\névolutivité. Le compromis, cependant, est qu'une interface uniforme dégrade l'efficacité,\npuisque les informations sont transférées sous une forme normalisée plutôt que sous une forme spécifique\naux besoins d’une application. L’interface REST est conçue pour être efficace pour\ntransfert de données hypermédia à gros grains, optimisation pour le cas classique du Web,\nmais aboutit à une interface qui n'est pas optimale pour d'autres formes d'interaction architecturale.\nPour obtenir une interface uniforme, plusieurs contraintes architecturales sont nécessaires pour guider le comportement des composants.\nREST est défini par quatre contraintes d'interface: identification des ressources; manipulation des ressources par\nreprésentations; messages auto-descriptifs; et hypermédia en tant que moteur de l'état de l'application.\n– Roy Fielding"},{"id":"text-17","heading":"Text","content":"Par la suite, les 4 contraintes suivantes, le noyau de REST, résultent des efforts déployés pour obtenir une interface uniforme entre différents composants.\n4.2. Toutes les ressources importantes sont identifiées par un mécanisme d'identificateur de ressource"},{"id":"text-18","heading":"Text","content":"induit une communication simple, visible, réutilisable et sans état"},{"id":"text-19","heading":"Text","content":"Roy l'explique très bien dans sa thèse:"},{"id":"text-20","heading":"Text","content":"Une ressource est un mappage conceptuel sur un ensemble d'entités et non sur l'entité qui correspond au mappage à un moment donné.\nPlus précisément, une ressource R est une fonction d’appartenance M variant dans le tempsR(t),\nqui pour le temps t mappe à un ensemble d’entités, ou valeurs, qui sont équivalentes.\nLes valeurs de l'ensemble peuvent être des représentations de ressources et / ou des identificateurs de ressources. […]\nCertaines ressources sont statiques dans le sens où, examinées à tout moment après leur création,\nils correspondent toujours au même ensemble de valeurs.\nD'autres ont un degré de variance élevé dans leur valeur au fil du temps.\nLa seule chose qui doit être statique pour une ressource est la sémantique du mappage,\npuisque la sémantique est ce qui distingue une ressource d’une autre.\n– Roy Fielding"},{"id":"text-21","heading":"Text","content":"4.3. Les ressources sont manipulées par l'échange de représentations"},{"id":"text-22","heading":"Text","content":"induit simple, visible, réutilisable, en mémoire cache et évolutif (masquage d'informations)"},{"id":"text-23","heading":"Text","content":"La représentation que nous exposons à partir de notre API publique pourrait être totalement différente de\nnotre mise en œuvre en interne ou comment les données sont stockées dans notre base de données.\nCela pourrait aussi être la même chose.\nNéanmoins, le client attend et doit manipuler toute ressource à l'aide de la représentation.\nnous exposons.\n4.4. Les représentations sont échangées via des messages auto-descriptifs"},{"id":"text-24","heading":"Text","content":"induit visible, évolutif, disponible via des systèmes multicouches, des caches partageables et cachables\ninduit évolutif via une communication extensible"},{"id":"text-25","heading":"Text","content":"Cela signifie que les données de la réponse doivent suivre le type de média que le client\ndemandé et comprend.\nÉtant donné que le client a négocié pour ce type de média, il devrait être capable d'analyser et de comprendre n'importe quelle partie de la réponse."},{"id":"text-26","heading":"Text","content":"L’interaction est sans état entre les demandes, les méthodes standard et les types de support sont utilisés pour\nindiquer la sémantique et échanger des informations, et les réponses indiquent explicitement la possibilité de mise en cache.\n– Roy Fielding"},{"id":"text-27","heading":"Text","content":"Si notre type de média est très faible (comme application / json) et nous avons besoin de fonctionnalités que le type de support ne décrit pas\nEnsuite, nous devons définir un autre type de support qui décrira la nouvelle sémantique et attendre que le ou les clients intègrent les nouvelles modifications du type de support.\nBriser la sémantique de notre type de support, ou simplement lui ajouter de nouvelles fonctionnalités, aura exactement le même résultat pour le client:\nmessages non descriptifs qui nécessiteront des informations hors bande, telles que la documentation.\n4.5 L'hypertexte en tant que moteur de l'état de l'application (HATEOAS)"},{"id":"text-28","heading":"Text","content":"induit simple, visible, réutilisable et pouvant être mis en cache grâce à une intégration orientée données\ninduit une évolutivité (couplage lâche) via une liaison tardive des transitions d'application"},{"id":"text-29","heading":"Text","content":"C’est l’une des parties les plus mal comprises du modèle REST de Roy. L'idée ici est que,\nune fois que le client et le serveur sont parvenus à un consensus sur le type de support après la négociation,\nla réponse du serveur doit fournir strictement toutes les options disponibles pour le client\npour manipuler la ressource et accéder à d’autres ressources, en utilisant la sémantique définie par\nle type de média accepté.\nComme le note Roy:"},{"id":"text-30","heading":"Text","content":"Une API REST doit être entrée sans connaissance préalable au-delà de l'URI initial (signet).\net un ensemble de types de supports standardisés adaptés au public cible\n(c’est-à-dire qu’il devrait être compris par tout client susceptible d’utiliser l’API).\nÀ partir de ce moment, toutes les transitions d'état de l'application doivent être pilotées par le client\nsélection des choix fournis par le serveur présents dans les représentations reçues\nou implicite par la manipulation de ces représentations par l'utilisateur.\nLes transitions peuvent être déterminées (ou limitées par) la connaissance du client des médias\ntypes et mécanismes de communication des ressources, qui peuvent tous deux être améliorés\nà la volée (par exemple, code à la demande).\n– Roy Fielding"},{"id":"text-31","heading":"Text","content":"cependant, L’une des conditions à remplir pour qu'HATEOAS fonctionne est que le type de média lui-même doit permettre\nà son vocabulaire hypermédia.\nPar exemple, avec application / json Type de support cela ne fonctionnerait pas comme JSON lui-même\n(application / json Le type de support n’est rien de plus qu’un JSON) ne fournit aucun de ces mécanismes.\nAu lieu de cela, le serveur et le client doivent s’accorder sur un format offrant de tels mécanismes.\nMalheureusement, la pratique courante est de mettre application / json dans notre en-tête Content-Type indiquant\nque le type de réponse suit ce type de média, puis à l'intérieur de la réponse, nous ajoutons\nsémantique concernant l'hypermédia. Ensuite, nous transmettons des informations hors bande au client,\ncomme la documentation, et exiger de les vérifier avant d'identifier l'analyse et l'utilisation de l'hypermédia\nsémantique de notre API.\n5. Clients et applications API\n5.1. Responsabilités du client et de l'application\nLes responsabilités du client et de l'application sont parfois mélangées.\nUn client est responsable de la compréhension, de l’interaction avec l’API et de la manipulation des ressources de l’API, en fonction de la sémantique du type de support.\net runtime HATEOAS. Le client est responsable de la fourniture dans l’application de la liste des ressources disponibles dans l’API,\nleurs champs, leurs capacités, les actions disponibles et tout hypermédia disponible.\nLa responsabilité de l'application, d'autre part, ne doit pas inclure les détails spécifiques à l'API.\nAu lieu de cela, en utilisant le client, il devrait extraire tout ce dont le domaine d’application a besoin, dans les limites des capacités de l’API.\nPensez aux appareils téléphoniques résidentiels traditionnels.\nLe fil téléphonique et ses signaux constituent l’API.\nLe périphérique utilisé pour coder / décoder les signaux de fil est le client API.\nSur un appareil, nous pouvons exécuter notre application.\nLe PSTN, le RNIS, le (A) DSL, etc. sont tous différents types de média pour la même API (signaux filaires).\nPour chacun d'eux, nous avons besoin d'un client (périphérique / modem) capable de comprendre (coder / décoder) les signaux de fil de ce type de support.\nEn utilisant ce client, nous pouvons créer n’importe quel type d’application, dans l’espace réalisable du type de support.\nL’application ne traite pas de la sémantique de l’API, mais utilise le client pour effectuer ses tâches.\n5.2. Le principe du facteur humain\nIl existe deux types d’intervention humaine lors de la création d’un client API:"},{"id":"text-32","heading":"Text","content":"1 fois: Programmer le client une seule fois pour comprendre correctement le type de support et laisser le\nle travail client pour toute API qui suit ce type de support même lorsque les API évoluent, étant donné qu'il est conforme aux spécifications de type de support.\nLa seule chose dont le client a besoin est l'URI initial de l'API.\nmulti-pli: Programmer le client une fois pour comprendre le type de média.\nModifiez ensuite le client pour analyser et comprendre correctement l’API à l’aide d’un contrat hors connexion.\n(documentation sur les ressources disponibles, les champs, la pagination, etc.), puis\nchaque fois que l'API évolue (par exemple, l'ajout d'une ressource ou d'un champ), reprogrammez le client en conséquence. L'étendue de l'implication humaine\npendant cette phase dépend de la faiblesse du type de média."},{"id":"text-33","heading":"Text","content":"Une API qui suit le modèle REST devrait être évolutive sans qu'il soit nécessaire\nd’implication humaine du côté client, étant donné que le client comprend le type de média.\nL’un des effets secondaires d’une telle évolutivité et d’un seul client est que la la gestion des versions ne doit pas avoir lieu dans l'URL mais dans le type de support lui-même."},{"id":"text-34","heading":"Text","content":"La gestion des versions d'une interface n'est qu'un moyen poli de tuer les applications déployées\nLa raison pour créer une véritable API REST est d'obtenir une capacité d'évolution… un «v1» est un moyen majeur pour vos clients d'API, indiquant RPC / HTTP (pas REST).\nRoy Fielding"},{"id":"text-35","heading":"Text","content":"6. REST appliqué dans une API moderne\nLors de l'ingénierie d'une API REST, il existe 2 approches:"},{"id":"text-36","heading":"Text","content":"concevoir une API spécialisée, généralement pilotée par l'interface utilisateur: les ressources et leur facilité de navigation sont étroitement associées à l'application spécifique conçue pour\nconcevoir une API générique, généralement pilotée par les données: les ressources sont plus génériques et les fonctionnalités de l’API permettent une multitude de transformations."},{"id":"text-37","heading":"Text","content":"Les API spécialisées pourraient être plus efficaces ou présenter des caractéristiques avantageuses cruciales pour le domaine, conçues pour\ncar ils ne sont optimisés que pour ce cas particulier.\nCependant, ils posent des problèmes lorsqu'ils doivent être réutilisés par toute autre application ne partageant pas la même interface utilisateur.\nEn conséquence, ces API sont très spéciales et un peu rares.\nD'autre part, les API pilotées par les données sont plus génériques et facilitent toute application pour demander les données optimisées.\n(dans le cadre des capacités de l’API) pour son cas d’utilisation.\nPouvoir spécifier les besoins de notre application lors de la demande de données à partir d’une API est crucial,\nsurtout si notre activité dépend de la capacité d’adoption de notre API.\nPour les sous-sections suivantes, nous nous concentrerons principalement sur les API de données génériques,\nCependant, la plupart des choses mentionnées ici peuvent également être appliquées dans une API spécialisée ou pilotée par une interface utilisateur.\n6.1. Exigences d'une API REST moderne\nLe modèle REST est conçu pour la communication de machine à machine de tout type.\nCependant, comme cette forme de communication devient de plus en plus courante,\nles clients attendent plus d'options (capacités) de la part du serveur pour leurs réponses.\nIl ne suffit pas de demander et d’obtenir la ressource, mais nous devrions pouvoir spécifier\nau serveur quelles transformations devraient s'appliquer, selon nos besoins.\nDe nos jours, nous utilisons tellement les API en réseau que nous devons essentiellement\nfournir un ORM au client via HTTP (ou tout autre protocole).\nNous fournissons ici une liste de fonctionnalités (nous les appelons capacités) qui, selon nous, devraient être intégrées à une API réseau moderne,\nen 2017.\n6.1.1. Champs clairsemés (collection / ressource)\nLe client doit pouvoir demander et obtenir des attributs spécifiques (c'est-à-dire un sous-ensemble) de la représentation des ressources.\nÉgalement liée, il convient de noter qu’une représentation d’une ressource pourrait avoir un ensemble de\nattributs pour différents clients, généralement en fonction des autorisations du client ou du rôle utilisateur qu’il représente.\n6.1.2. Associations à la demande (collection / ressource)\nLe client doit pouvoir demander aux associations associées à la ressource initiale principale, dans la même demande.\nCe qui différencie une association d’un attribut est que le premier a\nune identification dédiée. De plus, si l’API expose l’association en tant que ressource dédiée,\nl'identifiant peut être utilisé comme identification.\nLe client doit pouvoir trier en fonction d'un ou de plusieurs attributs et paginer la collection.\nbasé sur la page, la taille de la page et éventuellement un décalage.\n6.1.4. Filtrage des collections (collection uniquement)\nLe client doit pouvoir exécuter n’importe quel type de filtrage de collection, tant qu’il ne pose pas\ntoute menace à la sécurité ou ralentit les performances de l'API.\n6.1.5. Requêtes d'agrégation (collection uniquement)\nLe client doit pouvoir exécuter n’importe quelle requête d’agrégation, tant que cela ne pose pas\ntoute menace à la sécurité ou ralentit les performances de l'API.\n6.1.6. Types de données !\nLe client doit connaître les types de données des attributs de la représentation demandée d'une ressource.\nLes formats de message fournissent certains types de données mais ils sont plutôt basiques.\nPar exemple, JSON définit Chaîne, Booléen, Nombre, Tableau, et nul.\nRien de plus que cela, nous devons le définir dans les documentations.\nNous pensons que ces 5 types de données fournis par JSON ne sont qu’une blague pour les API modernes et que nous devrions\navoir une liste beaucoup plus grande d'options à sélectionner.\nEn outre, nous devrions pouvoir fournir des types personnalisés de manière simple. Par exemple, un champ est Chaîne mais\na une longueur maximale de 255 caractères, il suit une expression rationnelle spécifique, etc.\n6.1.7 Twist complot: cette liste est sans fin\nBien que nous sentions que aujourd'hui ces capacités devraient exister dans toute API moderne, Cette liste n'est pas exclusive.\nEn fait, il pourrait y avoir des capacités à l’avenir qui pourraient ne pas sembler nécessaires aujourd’hui.\nPar exemple, joignant une ou plusieurs ressources, d’autres opérations inspirées de la base de données appliquées aux ressources,\ninternationalisation et localisation des données, serveur HTTP / 2 Push sur certaines requêtes, livraison d'événements génériques à l'aide de HTTP Push sur d'autres\nressources sur des états spécifiques et d’autres capacités que nous n’avons même pas imaginées.\nDans tout les cas, ces capacités doivent être transparentes et auto-descriptives pour le client, sans aucune documentation ni implication humaine, autre\nque de programmer le client pour prendre en charge le ou les types de média et de le pointer vers l’URI d’API initial.\n6.2. Types de média vs HATEOAS\nMaintenant, le lecteur pourrait se demander: où est le lieu approprié pour décrire ces capacités,\ndans le type de support de notre API ou en utilisant HATEOAS?\nQu'est-ce qui va où?\n6.2.1. Définir un nouveau type de support n'est pas facile et doit être évité\nLa création d'un nouveau type de support pour notre API est généralement considérée comme une mauvaise pratique.\nCréez un nouveau type de support uniquement si vous êtes certain qu'aucun des éléments déjà publiés\nLes types de supports peuvent s'intégrer dans la conception de votre API.\nEn outre, étendre un type de média existant ou ajouter un type de média complémentaire à un\nexistant (comme application / vnd.api + json + my_custom_data_types) ne fonctionnerait pas.\nNon seulement la spécification de type de support existante ne fournit aucun principe d'extensibilité,\nmais aussi, la raison principale est que le client doit comprendre le type de média avant de commencer.\nPar conséquent, si nous souhaitons utiliser certains Nouveau types personnalisés dans notre API (déjà déployée), nous devrions publier\nle type de média avant la main et laissez humains implémenter du code pour analyser complètement les réponses de l'API qui\nsuivez ce type de support ou les réponses de l'API que leur type de support inclut également ce nouveau type de support.\n6.2.2. HATEOAS peut devenir assez lourd\nImaginez si nous devons décrire dans une ressource toutes les actions disponibles ainsi que l'API disponible\ncapacités dans cette ressource spécifique.\nLa réponse de notre API exploserait simplement en termes de taille tout en rendant notre API super complexe.\n6.2.3. Équilibrage entre types de média et HATEOAS\nL’idée est que les types de média décrivent les capacités génériques alors que HATEOAS\ndécrire les capacités spécifiques aux ressources.\nCependant, nous devrions noter que Les types de média ne sont pas analysés par le client (il n'y a jamais eu une telle intention de toute façon)\nce qui signifie que le client doit être préalablement programmé par un humain afin de prendre en charge ce type de support.\nPar conséquent, le type de support ne peut pas être très restrictif, car cela limiterait la liberté du concepteur d’API.\npour concevoir l’API comme elle le souhaite.\nPar exemple, pour la pagination, la plupart des API RESTy utilisent un page et un par page paramètre dans l'URL.\nSi le type de support décrit comment paginer en utilisant, par exemple, un modèle d’URL sur le chemin de la ressource (comme / ressource? page = page & per_page = per_page & offset = offset)\ncela voudrait dire que tout Les API qui suivent ce type de support doivent avoir la pagination qui suit ce modèle d’URL.\nLe niveau de restriction devient plus évident lors de la description de capacités plus complexes.\nEn revanche, si tout le monde suit ce type de média, il est plus facile de programmer nos clients.\nPlus précisément, en particulier lorsque le type de support est restrictif, si nous créons un client qui analyse les réponses à l’aide de ce type de support.\nEnsuite, il est facile de la "configurer" pour une autre API qui suit également le même type de média.\nHATEOAS devrait essentiellement complément type de média en fournissant la sémantique définie par le type de média hypermédia dans runtime\npour que le client fonctionne correctement.\nPar exemple, HATEOAS pourrait décrire, ressource par ressource, si la pagination est prise en charge, quel est le maximum par page etc.\n6.2.4. Une architecture alternative\nNous pensons que la spécification et l'utilisation actuelles du type de média sont obsolètes.\nSi le génie logiciel nous a appris quelque chose, c'est que la composition peut appliquer le principe de responsabilité unique, si elle est utilisée correctement.\nInspirés par cela, nous proposerons ultérieurement un nouveau concept: les MicroTypes, de petits modules réutilisables combinés ensemble, peuvent former un type de support.\nEn conséquence, les clients devraient pouvoir même négocier des parties du type de support et non le type de support dans son ensemble.\nDe plus, au lieu de mélanger les données avec HATEOAS dans les réponses de l'API, nous introduirons l'introspection de nos ressources.\n7. Spécifications de l'API aujourd'hui\nMaintenant que nous avons défini ce que REST est, selon Roy, quelles fonctionnalités les API modernes devraient prendre en charge et où\nils devraient leur fournir,\nvoyons les spécifications des API REST (y) disponibles à compter d’aujourd’hui, septembre 2017, ce qu’elles fournissent et comment\nceux-ci suivent de près le modèle REST.\n7.1. Notre cas d'utilisation\nNotre cas d'utilisation est une miniature d'une autre application sociale.\nPlus précisément, dans notre domaine API, nous avons un Utilisateur ressource qui a d'autres ressources associées, comme Micropost, Comme, etc\nPour notre format de message, nous utiliserons JSON car c’est le plus populaire, mais il pourrait s’agir de XML, YAML, etc."},{"id":"text-38","heading":"Text","content":"Utilisateur"},{"id":"text-39","heading":"Text","content":"identifiant, une chaîne, jamais vide ou NULL, ID principal de la ressource\nemail, une chaîne, jamais vide ou NULL, avec une longueur maximale de 255 caractères, format de courrier électronique\nprénom, une chaîne, avec une longueur maximale de 150 caractères\ndate de naissance, une chaîne représentant une date en fonction de iso8601, dans 2017-04-01 format.\ncréé à, une chaîne, jamais vide ou NULL, représentant un DateTime selon iso8601, en UTC\nmicroposts_count un nombre entier"},{"id":"text-40","heading":"Text","content":"Donc, étant donné ces propriétés de modèle REST nous pourrait avoir les itinéraires suivants:"},{"id":"text-41","heading":"Text","content":"Utilisateurs Ressource (/ api / utilisateurs):"},{"id":"text-42","heading":"Text","content":"Liste des utilisateurs (GET / api / utilisateurs): Obtient une collection de Utilisateur Ressources\nCréer un nouvel utilisateur (POST / api / utilisateurs): Crée un nouveau Utilisateur avec les attributs spécifiés."},{"id":"text-43","heading":"Text","content":"Utilisateur Ressource (/ api / utilisateurs / id):"},{"id":"text-44","heading":"Text","content":"Obtenir un utilisateur (GET / api / users / id): Obtient les attributs du spécifié Utilisateur\nMettre à jour un utilisateur PATCH / api / utilisateurs / id: Met à jour un Utilisateur avec les attributs spécifiés\nSupprimer un utilisateur DELETE / api / users / id: Supprime un Utilisateur"},{"id":"text-45","heading":"Text","content":"Utilisateurs et Utilisateur sont deux ressources distinctes qui sont souvent, à tort, considérées comme une seule et même ressource.\nEn outre, le fait que Utilisateurs est une collection de Utilisateur les objets, c’est parce que cela répond à nos besoins, mais il n’a pas nécessairement\nêtre comme ça.\nComme nous l'avons mentionné, Utilisateur la ressource a aussi des associations (ou des relations / relations si vous préférez),\ncomme Micropostes.\n7.1.1. Ressource utilisateur\nEn langage JSON simple, la ressource utilisateur devrait ressembler à ceci:"},{"id":"text-46","heading":"Text","content":""utilisateur": \n "id":"685",\n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance": "1988-12-12",\n "créé à": "2014-01-06T20: 46: 55Z",\n "microposts_count":50"},{"id":"text-47","heading":"Text","content":"7.1.2. Ressource utilisateurs (une collection de ressources utilisateur)\nUne collection de Utilisateur les ressources, les Utilisateurs ressource, ressemblerait à:"},{"id":"text-48","heading":"Text","content":"{\n "utilisateurs": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance": "1988-12-12",\n "créé à": "2014-01-06T20: 46: 55Z",\n "microposts_count":50\n , \n "id":"9124",\n "email": "[email protected]",\n "prénom": "Robert Clarsson",\n "date de naissance": "1940-11-10",\n "créé à": "2016-10-06T16: 01: 24Z",\n "microposts-count": 17,\n ]"},{"id":"text-49","heading":"Text","content":"Maintenant que nous avons défini la portée de notre petite API, voyons comment cela serait implémenté.\ndans les spécifications pour les API REST (y) actuellement disponibles. Nous pensons que la plupart des API actuellement déployées\nont beaucoup de similitudes avec les spécifications suivantes, à savoir la structure et la partie HATEOAS (en ce qui concerne\nliaison), et par conséquent en comparant ces spécifications avec notre modèle serait suffisant.\nNous évaluerons les spécifications pour ce qui suit:"},{"id":"text-50","heading":"Text","content":"si elles suivent le modèle REST de Roy\nsi leurs messages sont ne pas auto-descriptif, autrement dit, prendre en charge le type de média de l’API dans notre client\nnous devons également lire et comprendre la documentation pour développer notre client\nsi elles requièrent un facteur humain multiplicatif pendant que l'API évolue"},{"id":"text-51","heading":"Text","content":"7.2. JSONAPI\nJSONAPI a été créé à l'origine par Yehuda Katz, dans le cadre de la bibliothèque de données des braises d'Ember.\nDepuis lors, beaucoup de gens ont contribué et sont devenus l’un des pays les plus soutenus\nSpécifications API à partir de 2017 en termes d'outils et de bibliothèques.\n7.2.1. Ressource utilisateur"},{"id":"text-52","heading":"Text","content":"{\n "Les données": \n "id":"1",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance":"1988-12-12",\n "créé à":"2014-01-06T20: 46: 55Z",\n "microposts-count":50\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 1"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 1"\n \n \n \n \n}"},{"id":"text-53","heading":"Text","content":"7.2.2. Ressource utilisateurs (une collection de ressources utilisateur)"},{"id":"text-54","heading":"Text","content":"{\n "Les données":[[[[\n \n "id":"1",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Filippos Vasilakis",\n "date de naissance":"1988-12-12",\n "créé à":"2014-01-06T20: 46: 55Z",\n "microposts-count":50\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 1"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 1"\n \n \n \n ,\n \n "id":"9124",\n "type":"utilisateurs",\n "les attributs": \n "email":"[email protected]",\n "prénom":"Robert Clarsson",\n "date de naissance":"1940-11-10",\n "créé à":"2016-10-06T16: 01: 24Z",\n "microposts-count":17\n ,\n "des relations": \n "micropostes": \n "liens": \n "en relation":"/ api / microposts? user_id = 9124"\n \n ,\n "aime": \n "liens": \n "en relation":"/ api / likes? user_id = 9124"\n \n \n \n \n ],\n "liens": \n "soi":"/ api / users? page = 1 & per_page = 10",\n "suivant":"/ api / users? page = 2 & per_page = 10",\n "dernier":"/ api / users? page = 3 & per_page = 10"\n \n}"},{"id":"text-55","heading":"Text","content":"7.2.3. Des reflets\nBien que la spécification fasse de gros efforts pour décrire la structure du document, nous voyons quelques\nproblèmes notables. À savoir:"},{"id":"text-56","heading":"Text","content":"Liens limités (pas de modèles d'URI, le client est considéré comme idiot)\nAucune action\nAucune information sur les attributs disponibles\nAucune information sur les types de données\nAucune description d'attributs"},{"id":"text-57","heading":"Text","content":"To sum up, it doesn’t entirely follow REST model while it requires both\ndocumentation and multi-fold human factor.\n7.3. HAL\nHAL was created by Mike Kelly in 2012.\nThe key feature of HAL when it was released was the browsability/explorability of any API that adopted.\nAnother feature is the idea of curies, links inside the resource that lead to the documentation, targeted to\nhumans and not machines.\nThe resources of our use case that are presented here use JSON as a message format, but HAL is not tied to that.\n7.3.1. User resource"},{"id":"text-58","heading":"Text","content":""_links": \n "self": \n "href": "/api/users/id"\n ,\n "microposts": \n "href": "/api/microposts/user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": "1",\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,"},{"id":"text-59","heading":"Text","content":"7.3.2. Users resource (a collection of User resources)"},{"id":"text-60","heading":"Text","content":"{\n "_links":\n "self":\n "href":"/api/users"\n ,\n "curries":[[[[\n \n "name":"ea",\n "href":"https://example.com/docs/rels/rel",\n "templated":vrai\n \n ]\n ,\n "_embedded":{\n "users":[[[[\n \n "_links":\n "self":\n "href":"/api/users/id",\n "templated": vrai\n ,\n "microposts":\n "href":"/api/microposts?user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": 9123,\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50\n , \n "_links":\n "self":\n "href":"/api/users/id",\n "templated": vrai\n ,\n "microposts":\n "href":"/api/microposts?user_id=id",\n "templated": vrai\n ,\n "likes": \n "href": "/api/likes/user_id=id",\n "templated": vrai\n \n ,\n "id": 9123,\n "name": "Robert Clarsson",\n "email": "[email protected]",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 50,\n \n ]\n }\n}"},{"id":"text-61","heading":"Text","content":"7.3.3. Reflections\nAlthough this spec does have templated links, we see some notable issues. Namely:"},{"id":"text-62","heading":"Text","content":"No actions (they are supported by an unofficial extension)\nNo info on available attributes\nNo info on data types\nNo attributes description, requires documentation (however it does provide a link to documentation, through curries)"},{"id":"text-63","heading":"Text","content":"To sum up, it doesn’t entirely follow REST while it requires documentation and multi-fold human factor (curies facilitate that).\n7.4. Sirène\nSiren was created by Kevin Swiber in 2012 and revolves around entités, a URI-addressable resource that has properties and actions associated with it.\nThe resources of our use case that are presented here use JSON as a message format, but Siren is not tied to that.\n7.4.1. User resource"},{"id":"text-64","heading":"Text","content":""class": [[[[ "user" ],\n "Propriétés": \n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,\n ,\n "actions": [[[[\n \n "name": "get-user",\n "Titre": "Get User",\n "method": "OBTENIR",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n ,\n \n "name": "update-user",\n "Titre": "Update User",\n "method": "PUT",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n "fields": [[[[\n "name": "name", "type": "text" ,\n ]\n ,\n \n "name": "delete-user",\n "Titre": "Get User",\n "method": "DELETE",\n "href": "https://example.com/api/users/1",\n "type": "application/json",\n \n ],\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/1" ,\n "rel":[[[["microposts"], "href":"/api/microposts?user_id=1" \n "rel":[[[["likes"], "href":"/api/likes?user_id=1" \n ]"},{"id":"text-65","heading":"Text","content":"7.4.2. Users resource (a collection of User resources)"},{"id":"text-66","heading":"Text","content":""class":[[[["users"],\n "Propriétés":nul,\n "entities":[[[[\n \n "class":[[[["user"],\n "rel":[[[["https://example.com/users/1"],\n "href":"https://example.com/users/1",\n "Propriétés":\n "name": "Filippos Vasilakis",\n "email": "[email protected]",\n "createdAt": "2014-01-06T20:46:55Z",\n "micropostsCount": 50,\n ,\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/1" ,\n "rel":[[[["microposts"], "href":"/api/microposts?user_id=1" \n ]\n ,\n \n "class":[[[["user"],\n "rel":[[[["https://example.com/users/9124"],\n "href":"https://example.com/users/9124",\n "Propriétés":\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ,\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com/api/users/9124" ,\n "rel":[[[["microposts"], "href":"https://example.com/api/microposts?user_id=9124" \n "rel":[[[["likes"], "href":"https://example.com/api/likes?user_id=9124" \n ]\n \n ],\n "actions":[[[[\n \n "name":"create-user",\n "Titre":"Create User",\n "method":"POST",\n "href":"https://example.com/users/",\n "type":"application/json",\n "fields": [[[[\n "name": "name", "type": "text" ,\n "name": "email", "type": "text" ,\n "name": "birth_date", "type": "date" ,\n ]\n \n ],\n "links":[[[[\n "rel":[[[["self"], "href":"https://example.com.api/users",\n "rel":[[[["next"], "href":"https://example.com.api/users?page=2"\n ]"},{"id":"text-67","heading":"Text","content":"7.4.3. Reflections\nThe spec takes a huge leap towards REST principles by supporting, links, actions with fields and data types, there are\nstill some issues that require human-involvement:"},{"id":"text-68","heading":"Text","content":"No custom types for the attributes of actions\nNo info on available and required attributes\nNo info on data types on response objects\nLimited description for fields and resources"},{"id":"text-69","heading":"Text","content":"To sum up, Siren is very close to a self-described REST API but in practice it requires documentation and multi-fold human factor.\n8. Ideal REST API\nHow many years these specs could sustain in terms of evolvability ? Are they built with a lifespan of 2-3 years or are they\nbuilt with a life span of 50 years?\n8.1. Capabilities of an Ideal REST API\nIn an ideal REST API, the client should be able to have all the necessary information for both\nthe request and response."},{"id":"text-70","heading":"Text","content":"About each resource returned from the API to the client:"},{"id":"text-71","heading":"Text","content":"default attributes and available (superset of default) attributes of the resource, based on the user’s permissions\ndata types for each attribute in the resource or any embedded association\nSorting/pagination, filtering and aggregation queries availability\ndata type of each attribute\ndefault embedded associations and available associations to embed"},{"id":"text-72","heading":"Text","content":"recursively apply the same information for each association available for embedding"},{"id":"text-73","heading":"Text","content":"any other capability (HTTP/2 Server Push, event delivery etc)"},{"id":"text-74","heading":"Text","content":"About each resource sent to the API from the client"},{"id":"text-75","heading":"Text","content":"available actions on the resource\nattributes, per action, the client can modify, based on the user’s permissions\nrequired attributes of a resource (attributes a resource doit before sending it over)\ndata types of the attributes (could be different from the resource found in the response)\nassociations that are required or can be embedded to the initial request"},{"id":"text-76","heading":"Text","content":"recursively apply the same information for each association available for embedding"},{"id":"text-77","heading":"Text","content":"Bien que cette liste n'est pas exhaustive, an architecture style is timeless anyway,\nwe feel that the aforementioned capabilities ought to appear in an idealized modern REST API.\nWe should also note that the reason we don’t mention anything about the headers that are required, or, the status codes\nis because we feel that these belong to the Protocol level and not in the Application level.\nAny changes on this level imply that the API breaks the protocol.\nHowever, we are pragmatic and we understand that an API designer could want to ajouter (not change)\na status code or a header in a given request/response and as a result, ideally, this should also be possible to be described.\n8.1.1. Today’s REST is far from ideal\nNow to the reader, it should be obvious that even if we manage to offload some of the aforementioned information\nto the Media Type, we would still have a très complex, massive, response from the server that mostly includes HATEOAS\nand not actual data.\nIn our experience, such responses are very hard to implement correctly, test, be performant and even debug. Après tout,\na human will sit down and write the initial code and debugging the code by the eye is important.\nSimplicity is crucial.\nMoreover, some clients might not be interested in hypermedia and evolvability at all but only the data.\nHowever such APIs force the clients to deal with it.\nIdeally we would like to give the option to the client to decide the extend of the hypermedia that it\nwill support and follow, without taking on defaults. Some clients might want to follow 100% the HATEOAS part\nof the API (and as a result be evolvable) some other clients might want the 50%, some clients might be interested\nonly in data.\nBy outputting a whole bunch of hypermedia-related information to the clients that, after all, might never use\nthem is a bad practice.\n8.1.2. Making an API REST-compliant by downplaying its capabilities\nOne could argue that we require all APIs to support features that they shouldn’t, like resource manipulation.\nFor instance, we could have a weather API with application/vnd.weather+yaml Media Type\nthat is only supposed to provide a single attribute with its value, as Integer:\nThis API devrait be REST-compliant by not providing any API capabilities, hypermedia or actions.\nOf course, the imaginary Media Type application/vnd.weather+yaml is supposed to provide all the necessary information\nbecause otherwise the client would fail to understand things like"},{"id":"text-78","heading":"Text","content":"what are the attributes of the response\nwhat is the data type of the temperature value (float, double, integer, bignum etc)"},{"id":"text-79","heading":"Text","content":"We feel that although this is true, most APIs are not as simple as that.\nMoreover such APIs can’t actually be evolved without releasing a new Media Type and breaking the existing API clients.\nThere is no way of introducing change, which essentially breaks REST’s principles.\nHowever we are pragmatic: we understand that such APIs will exist and API designers want to spend as less time as possible to build such APIs.\nIntrospected REST, an architecture that we will describe later, solves that by serving hypermedia\ninformation on side and in an incremental way without breaking the simplicity.\n8.1.3. A JSON API back in time\nA JSON-based API built around 2006 would return just data. No hypermedia, no HATEOAS, only data.\nIn our use case, User resource would look like this:"},{"id":"text-80","heading":"Text","content":""user": \n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50"},{"id":"text-81","heading":"Text","content":"As simple as that.\nCompared with a HATEOAS-ed response it’s simple as hell, obvious, easy to debug and understand by a human (and a client).\nIs it possible to build an API that is simple as that, be Hypermedia driven and give the client the option to decide\nthe level and type of HATEOAS it will follow?\n8.2. Deriving the need for a new model\n8.2.1. REST is complex\nAs we described earlier, mixing data with hypermedia leads to increased complexity, for both the server and the client.\nJust compare the size of our resource’s data and the size of our resource when represented by\nSiren, a hypermedia-ed API that doesn’t even being REST-compatible by missing numerous information as described\nin its reflections.\nImagine how bloated the response would look like, if we added all the capabilities described in section 6.1.\nMoreover, the hypermedia must be tailored for the user role the client acts on behalf of.\nFor instance, a user with very basic access role might only have access to retrieving resources and not manipulating them.\nOr such role could only have access to specific capabilities of the API.\nAs a result, the hypermedia provided on the response object should reflect that by not providing hypermedia that will lead to unauthorized access.\nIn fact, such design is quite difficult to implement and test from the server side.\n8.2.2. REST enforces possibly useless information\nIn REST, even if the hypermedia are rendered by taking into account the user’s role, eventually we might send more data that the client wants.\nExactly because we don’t know in advance what the client might need, we must send all the possible hypermedia information to the client, just in case.\nThe client however could only be interested in the data, or specific hypermedia types, like links, but instead gets a fully bloated response by the server.\n8.2.3. REST sacrifices performance for evolvability\nComplex or long-lived APIs tend to have many hypermedia data (links, actions, custom metadata)\nrelated to the resource itself, its associations and related resources.\nAs a result, even if the actual data could be very small the resulted response object gets much larger in size slowing down the server rendering\nand the client receiving and parsing.\nThe performance issues become more apparent on lossy networks like mobile clients, a trend that has increased over the past decade,\nor on constrained devices and environments, like IoT.\n8.2.4. REST does not support caching of hypermedia\nIn practice, the hypermedia part of a resource rarely changes, compared to the resource’s data.\nIn REST, by design, the client can’t cache the hypermedia part of the resource, even for relatively small amount of time, because\nhypermedia is part of the resource, thus caching the hypermedia can’t be separate from caching the response itself.\n8.2.5. REST doesn’t make it easy to evolve hypermedia\nAnother issue of REST is that due to the fact that everything is mixed in together, evolving hypermedia separately from the data\ncan’t happen.\nWe understand that this is actually another feature of REST design and not an issue, treating a response object as a whole and not breaking into\ndifferent parts like hypermedia and data, however, in practice, this poses difficulties for easier evolvement and maintenance of the API.\n8.2.6. REST’s power is limited by HTTP and related protocols (SIP, CoAP etc)\nAlthough REST is not dependent on any protocol or spec, the truth is that it has dominated in HTTP.\nAs we described earlier, in protocols like HTTP, content negotiation between client and server is achieved using Media Types,\nwhich is the only mechanism to define the semantics of a response.\nGiven that composite Media Types never had real composability, and the fact that they cannot be parsed by clients,\nthere is a trade off between what should go to the Media Type and what to the actual response through\nhypermedia, as described in section 6.2.3.\nThis limits the design flexibility and evolvability.\nAs a result Media Types become big monoliths that are inflexible and limit the evolvability of the API.\n8.2.6.1. No backwards compatible with any RESTly or RESTless API\nIn a perfect world, APIs are built to be alive for many decades and clients are exploiting every little feature of the API and its Media Type.\nHowever, we are in a pragmatic world where nothing is perfect and clients are built by humans who take decisions based on their time and money.\nAlthough we firmly believe that a REST API is better than any RESTly or RESTless API, we understand that there could be cases where API designers\ndevoir initially skip hypermedia part.\nThe problem is that when REST is applied to HTTP, it doesn’t allow us to easily integrate hypermedia at a later point.\nThe reason is that, in a RESTless API, adding hypermedia at a later stage would mean that we would need a new Media Type because\notherwise it would break the current semantics.\nWe would like to see a model that embraces both architectural API styles:"},{"id":"text-82","heading":"Text","content":"APIs that are built to last decades and thus, support full hypermedia from the very first day of their release\nAPIs that don’t have hypermedia (the reason is none of our business), yet it is required to add hypermedia, later, in an incremental way without\nbreaking existing clients or limiting API’s flexibility"},{"id":"text-83","heading":"Text","content":"8.2.7.2 REST does not embrace composition\nAlthough REST does not rejects the idea of composability of different API capabilities using different specs in the same response, or composite Media Types,\nit doesn’t embrace it either.\nThe symptom of non-composability is clearly visible in protocols like HTTP where Media Types\nact as big monoliths trying to describe everything in one place.\nRFC 6906 (The ‘profile’ Link Relation Type) was created to overcome such issues\nbut as we will see later this specifications lags behind over true composability and\nproper negotiation of the different profile types from the client perspective.\nIn Introspected REST, the MicroTypes is a conceptual solution to the outdated Media Type concept\nand allows us to mix-in different concepts for different kind of metadata of a resource,\nyet have all of them on demand and separated by the actual data.\n9. Introspected REST"},{"id":"text-84","heading":"Text","content":"Simple things should be simple and complex things should be possible.\n— Alan Kay"},{"id":"text-85","heading":"Text","content":"In the following section we will describe our new architectural style based on a model for Networked APIs that goes beyond REST.\nThe model itself steps on Roy’s initial REST model but with the difference that instead of providing resource hypermedia at\nruntime, it provides them on the side, only if requested.\nHence, by keeping the interface uniforme the derived 3 out of 4 REST constraints that Roy defined still exist in this model:\nidentification of resources; manipulation of resources through representations et self-descriptive messages.\nHowever, instead of having the constraint of hypermédia en tant que moteur de l'état de l'application (HATEOAS), we have\nintrospection as the engine of application state (IATEOAS).\nMoreover, the introspection process can provide other kind of information, apart from hypermedia and links, that\ncan facilitate the client to take decisions on how to proceed with the application’s requests.\nTo achieve this, composition of different specs is a vital part of our model and for that we will use a new concept,\nMicroTypes, small reusable modules that a final Media Type can be composed of.\nBefore moving on, we will give concise definitions over hypermedia and metadata and break it down to different kinds of classes,\naccording to Introspected REST model.\nThese terms can overlap in the REST, however we feel that each one has its own place in our model that embraces composability.\n9.1. Data, metadata and hypermedia\n9.1.1. Les données\nData is the main variables of a resource, at a given state, at a given time.\nData is very volatile compared to other parts of a response.\n9.1.2. Hypermedia\nOriginally the hypermedia term was mostly used for linked data, in the sense of hyperlinks.\nIn REST, eventually, it also includes information for interaction and resource manipulation.\nHypermedia can be dynamic or static but regardless they are not considered part of the response data, because they define\nways to interact with the data.\nHypermedia is a very broad term and needs to be broken down in different parts.\nAlthough there isn’t any clear definition or consensus in the literature and the community, we will try to provide definitions and descriptions for\nall the different types of Hypermedia, according to our model’s perception.\n9.1.2.1. Liens\nThe most basic class of hypermedia, basically URIs that can be used to provide linking between related resources to the primary resource.\nThe properties of a link, like placement inside the response, strictly follow the semantics of the Media Type agreed.\n9.1.2.2. actes\nActions are links along with information for manipulating a resource.\nAlthough CRUD are the most popular actions of a resource, the beauty with REST, and consequently with Introspected REST,\nis that actions can go beyond plain CRUD.\nIn fact, we can define any type of action or meta-action of our internal resource, through the representation that we expose.\nAs a result, actions of a resource could be quite complex or simplistic depending on the needs and decisions of the API designer.\nActions should also describe any relevant information for the client to perform it, unless the Media Type itself describe those details.\n9.1.2.3. Forms\nAnother way of describing the manipulation options of a resource is the notion of forms.\nThe difference between actions and forms is that the latter are strictly semantically equivalent to an HTML form,\nfor the client to render.\n9.1.3. Metadata\nIf hypermedia is links and actions, then what is metadata ?\nMetadata are information about the resource that is not related with the data, including hypermedia.\nIn essence, metadata is a superset of hypermedia and it’s crucial for the client\nto understand API’s responses, access the API’s capabilities and manipulate the resources.\nMetadata could be API-specific, resource-specific, action-specific or even object-specific.\nThere could also be different kinds of metadata: runtime (i.e. pagination information), structural (i.e. data types of a resource object),\nhypermedia (i.e. links, actions, forms), informational targeted to humans (i.e. general information, descriptions), etc.\nUsually metadata is much less volatile than data, if not static, except runtime metadata\nthat depend on the request and the resource at the given time and state respectively.\n9.2. MicroTypes: reusable modules composing a Media Type"},{"id":"text-86","heading":"Text","content":"Imagine how poor the Web would have been if we had limited HTML to what was\nneeded by an FTP client. That’s what most JSON APIs are today.\n— Roy Fielding, on Gazouillement, 27 Aug 2016"},{"id":"text-87","heading":"Text","content":"We have been talking so much about the concept of MicroTypes but what exactly are ?\nCurrently, Media Types act as big monoliths that clients need to understand beforehand through human involvement.\nWe believe that Media Types should be broken in smaller\nreusable media types, MicroTypes, each describing very carefully a specific functionality of a modern API.\nThe reasoning is that, in our experience, we have seen that different APIs and API specs define the same functionalities in similar,\nbut not identical, ways.\nExamples of MicroTypes could be semantics for:"},{"id":"text-88","heading":"Text","content":"pagination\nquerying over url (applying filters, aggregations, pagination/sorting on a resource),\nresource/association inclusion in the same response\nsemantic/linked data\nhypermedia actions (required fields, available fields),\ndata types and resource schemas\ninformation d'erreur\nand more advanced, like HTTP/2 server push for specific resources/states etc"},{"id":"text-89","heading":"Text","content":"Each one of these could be defined as separate MicroTypes that specify in isolation how that part of the API works.\nAt the same time they should be generic enough or follow some specific semantics so that it’s possible to be referenced parent\nMedia Types targeted for Introspected APIs.\nThe parent Media Type doesn’t need to know in advance all the MicroTypes that the API designer intends to use\nbecause that would mean that adding new MicroTypes would require a new parent Media Type which consequently means breaking the clients.\nInstead, each MicroType should be attachable to a parent Media Type that defines introspected behavior and clients\nwould take into account only MicroTypes that are programmed to understand.\n9.2.1. Benefits of MicroTypes\nThe benefits when leveraging such architecture are multi-fold.\n9.2.1.1. Granular parameterization of API functionality by clients\nFirst, by allowing the client and server to do the regular negotiation flow even for those sub-media-types, the communication\nbetween the 2 ends is parameterized to the needs of the client, down to the semantics level.\nFor instance, a server might provide 3 MicroTypes for error information, each one having different representation or semantics.\nBy letting the server to decide the appropriate MicroType for the client by analyzing the client’s incoming request,\nmight not be efficient as the client can only send a part of its properties through the request, for various reasons like privacy concerns and performance,\nand thus the server has partial knowledge of the client’s state and properties.\nThe server has to make an arbitrary choice for the client, what it thinks it’s thinks best, using this partial knowledge.\nInstead, by giving the client the option to negotiate parts of the API functionality, we shift the responsibility towards the client\nto select the best representation and semantics of various, isolated, API functionalities.\nGiven that the client can know much more about its needs than the server, it will make the best available choice\nfor each API functionality, from the server’s options, which eventually will lead to the optimized combination of\nMicroTypes.\nAs we will see later, in HTTP protocol, this is called reactive negotiation, a forgotten but still valid negotiation mechanism.\n9.2.1.2. Reusability\nSecondly, the MicroTypes specs and possibly implementations can be re-used by both the servers and clients.\nInstead of defining a whole Media Type, API designers will be able to include various small modules\nthat extend the API functionality they way it’s needed.\nWe firmly believe that once the community defines a number of MicroTypes, it will be much easier for an API designer\nto design a new API by reusing the MicroTypes she thinks fit best to her needs.\n9.2.2. MicroType shims\nImagine that we want to use an existing spec as a MicroType, like JSON Schema.\nWe cannot create a MicroType out of it with just a reference\nto the original spec because it lacks the context of the underlying protocol (like HTTP) and Media Type with which it will be\nutilisé.\nIt also lacks information about the requirements of the parent Media Type and the compatibility with other MicroTypes.\nInstead, we need to extend the original spec with the necessary, additional, semantics in the context\nof Media Types.\nThose semantics should be as minimal as possible, with respect to the initial specification and without altering its core semantics\nbut enough for usage in its new context.\nWhen this method is followed, the new MicroType is called a “wrapper” or a “shim” of the original spec.\n9.3. Introspection as the engine of application state (IATEOAS)\nThe idea of introspection is to be able to examine properties of a system at runtime.\nIn the case of Introspected REST, introspection defines a process for a client to be able to introspect\nthe API’s, resource’s, action’s or even object’s metadata at runtime.\nThrough those metadata, server provides all the available states, manipulation actions as well as the available transitions.\nThe implementation of the process is up to the API designer although usually a RESTish interface even for each MicroType’s metadata is a wise choice.\nIn any case, we would like to point out some key properties that should appear on any introspection process.\n9.3.1. Composability over monoliths\nThe process should embrace the use of distinct MicroTypes to form a Media Type instead of using a single Media Type.\nSuch an architecture will lead to a system whose each MicroType’s metadata is independent, self-contained and detached from the metadata\nof the rest MicroTypes.\nThe API designer should premier investigate and embrace the use of MicroTypes, RFCs and specs that are already defined and published, instead of\ncreating her own custom, unpublished spec.\nThe reason for this suggestion is that creating a new spec is difficult and usually such custom specs are used only for domain-specific APIs that\nwere created for and live as long as this API is used.\nInstead, by trying to adapt published, battle-tested, RFC-community-reviewed specs assures the API designer in terms of compatibility,\nadoptability, clarity and possibly implementation, for both ends of the communication.\n9.3.2. Plain data separated from metadata\nThe process of introspection should be distinctly different from requesting data.\nTo that extend, introspection responses should not include any data but only metadata, and data\nresponses should not include any metadata, except, possibly, runtime metadata.\n9.3.3. Identifiable metadata of each Microtype\nGiven that metadata are already separated from plain data, by being able to identify and retrieve metadata\nof a specific MicroType there are various advantages because each MicroType becomes independent and self-sufficient.\nPar exemple, mise en cache will be possible using the underlying protocol’s mechanisms, for each metadata type separately.\nAnother example is the detached evolvability of each MicroType’s metadata, independently, given that the MicroType’s semantics permit that.\n9.3.4. Discovery of resource capabilities\nAn Introspected REST API devrait fournir capabilities discovery per resource that provides\nall the necessary information to the client to understand what it is possible to request from the API.\n9.3.5. Client bootstraping\nAn Introspected REST API devrait fournir un API-wide capabilities discovery that lists all MicroTypes that are used API-wide along\nwith resources that can be accessed directly and in general, any information that could be of interest and could help the client\nto bootstrap faster.\nThe location of this detailed list should be in the conceptual racine resource/URL of the API.\n9.3.6. Automatic documentation generation\nPossibly the API will provide a MicroType targeted to humans and not machines that contains informational descriptions and explanations.\nIl convient de noter que this information must not be needed for a client to parse and understand the API responses,\nand even for humans such information should weight very little compared to the rest metadata.\nIn the same way, the API should automate the generation of the documentation using all metadata from all MicroTypes for every resource.\nThe way the documentation is requested and its format should be distinctly defined by a MicroType or the parent Media Type.\n10. Introspected REST applied to HTTP\nIntrospected REST architectural style is not bound to any protocol or spec, just as is REST.\nHere we will review the challenges that are rising through its adaptation in HTTP protocol.\nFor instance, we need to solve issues like announcement and negotiation of MicroTypes bound to a Media Type,\npriority order in case of overlaps or collisions, identification, and\nthe actual introspection process in HTTP.\n10.1 Revisiting content negotiation in HTTP\nAs we have already seen, content negotiation in HTTP is achieved through Acceptez request header but it’s not the\nonly header which can be used by the server to determine the appropriate representation for the client.\nAccept-Charset, Accepter l'encodage, Accept-Language request headers can also be used.\nIn practice, User-Agent header is also used by the server for choosing the right content for the client\nbecause it contains some device and agent characteristics, although it’s not part of the standard negotiation headers.\nLately even, a new draft standard is being created, HTTP Client Hints,\nthat extends the HTTP with new request headers which indicate device and agent characteristics.\nThe server uses all those headers as hints in order to determine the most suitable representation of the content\nto be served to the client.\nThis hint-based mechanism, which according to RFC 7231 is called server-driven\nor proactive content negotiation, has been extensively used in HTTP protocol.\nIn the context of MicroTypes and Introspected REST, using this mechanism, the client\ncan negotiate for runtime MicroTypes: API functionalities that define semantics\nfor the data and runtime metadata.\nThis type of MicroTypes, should tend to appear less often because\nif anything can be introspected on the side instead of runtime, it will be\ndefined as non-runtime, introspective metadata.\nInterestingly, RFC 7231 notes that proactive negotiation has\nsome serious disadvantages:"},{"id":"text-90","heading":"Text","content":"Proactive negotiation has serious disadvantages:\no It is impossible for the server to accurately determine what might\n be “best” for any given user, since that would require complete\n knowledge of both the capabilities of the user agent and the\n intended use for the response (e.g., does the user want to view it\n on screen or print it on paper?);\no Having the user agent describe its capabilities in every request\n can be both very inefficient (given that only a small percentage\n of responses have multiple representations) and a potential risk\n to the user’s privacy;\no It complicates the implementation of an origin server and the\n algorithms for generating responses to a request; et,\no It limits the reusability of responses for shared caching.\n— RFC 7231"},{"id":"text-91","heading":"Text","content":"In fact, from the beginnings of HTTP (since RFC 2068, published in 1997),\nthe protocol allowed another negotiation type: agent-driven or reactive content negotiation negotiation,\nthat matches very well our introspective concept.\nAs RFC 7231 notes, in reactive content negotiation the server provides a\nlist of options to the client to choose from."},{"id":"text-92","heading":"Text","content":"With reactive negotiation (a.k.a., agent-driven negotiation),\n selection of the best response representation (regardless of the\n status code) is performed by the user agent after receiving an\n initial response from the origin server that contains a list of\n resources for alternative representations.\n(…)\nA server might choose not to send an initial representation, other\n than the list of alternatives, and thereby indicate that reactive\n negotiation by the user agent is preferred. Par exemple, le\n alternatives listed in responses with the 300 (Multiple Choices) and\n 406 (Not Acceptable) status codes include information about the\n available representations so that the user or user agent can react by\n making a selection.\n— RFC 7231"},{"id":"text-93","heading":"Text","content":"With reactive negotiation, the client is responsible for choosing the most appropriate representation,\naccording to its needs.\nThat goes inline with Introspective REST, as the client, after receiving all the possible server options,\nuses the ones that best fit to its use case or understands better.\nAs the RFC notes, such negotiation has the advantage of choosing the best combination of MicroTypes,\nbecause the client does the selection out of a predefined list that the server publishes.\n10.2. Runtime MicroTypes\nRuntime MicroTypes are targeted for API functionality that is used during the request/response cycle\nof plain data.\nSuch functionality could be pagination, URI querying language, error descriptions etc or it could even be\nsemantics around the data itself.\nIt should also be noted that even runtime MicroTypes could have content for introspection but the key difference\nfrom pure introspective MicroTypes is that part of their functionality affects the semantics of the client’s request\nor server’s response.\nThe negotiation of runtime MicroTypes should follow the regular negotiation flow:\nThe client should negotiate for the principal Media Type using the Acceptez demande\nheader and the server responds with Type de contenu response header, denoting the selected representation.\nHowever the key difference is that for each principal Media Type, it should also\nnegotiate for the MicroTypes to be used with it.\nFor that, we will employ the Media Type parameters, a rarely used mechanism:"},{"id":"text-94","heading":"Text","content":"Media types MAY elect to use one or more media type parameters, or\n some parameters may be automatically made available to the media type\n by virtue of being a subtype of a content type that defines a set of\n parameters applicable to any of its subtypes. In either case, the\n names, values, and meanings of any parameters MUST be fully specified\n when a media type is registered in the standards tree, and SHOULD be\n specified as completely as possible when media types are registered\n in the vendor or personal trees.\nParameter names have the syntax as media type names and values:"},{"id":"text-95","heading":"Text","content":"parameter-name = restricted-name"},{"id":"text-96","heading":"Text","content":"— RFC 6838"},{"id":"text-97","heading":"Text","content":"An example of an imaginary Media Type with a couple of parameters for MicroTypes is:"},{"id":"text-98","heading":"Text","content":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql;"},{"id":"text-99","heading":"Text","content":"In the aforementioned example, the client asks for representation of application/vnd.api+json,\n(which as we have seen earlier it vaguely means a vendor application that follows the semantics of api, in JSON representation)\nbut wants the pagination to follow the semantics of simple-spec and the querying language of graphql.\nThe client should be able to even set a preference order:"},{"id":"text-100","heading":"Text","content":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi;"},{"id":"text-101","heading":"Text","content":"Here the client shows preference to the imaginary graphql querying language but if that doesn’t exist\nthen it will accept the jsonapi querying language.\nIt should be noted that this preference is different from a Media Type preference using the relative\npoids q parameter (also called quality value) as it applies to the MicroType level.\nAn example with multiple Media Types could be:"},{"id":"text-102","heading":"Text","content":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi, application/vnd.api2+json; pagination=simple-spec; querying=jsonapi; querying=jsonapi; q=0.9"},{"id":"text-103","heading":"Text","content":"In this example the client shows preference to the application/vnd.api+json Media Type (it has default quality value of 1.0)\nwith specific preferences on MicroType level, as we explained above.\nHowever if this Media Type is not available then it will accept the next most preferred, application/vnd.api2+json, by requesting\nspecific MicroTypes.\nIf the server can provide only the less preferred Media Type with the less preferred querying it would answer:"},{"id":"text-104","heading":"Text","content":"Content-Type: application/vnd.api2+json; pagination=simple-spec; querying=graphql"},{"id":"text-105","heading":"Text","content":"10.3. Introspective MicroTypes\nIntrospective MicroTypes don’t alter the semantics of request/response cycle but are still valuable to the client\nand the decisions they should take based on the current state and the input from the application developer.\nThey can provide information about the data types, RDF Schema of the resources, etc.\nIntrospective MicroTypes should employ reactive negotiation.\nThe question though is how can the server advertise the availability of MicroTypes for the client\nto introspect.\nIdeally we would like to inform the client for all possible options through HTTP instead of employing a serialization format.\nUnfortunately, the HTTP protocol doesn’t say much about this type of negotiation, only that the status code when requesting\nsuch information should be 300 and Lien relation header of RFC 5988 could be potentially used\nto provide the list with all the available options,\nmostly for historical reasons that date back to RFC 2068:"},{"id":"text-106","heading":"Text","content":"The 300 (Multiple Choices) status code indicates that the target\n resource has more than one representation, each with its own more\n specific identifier, and information about the alternatives is being\n provided so that the user (or user agent) can select a preferred\n representation by redirecting its request to one or more of those\n identifiers. In other words, the server desires that the user agent\n engage in reactive negotiation to select the most appropriate\n representation(s) for its needs (Section 3.4). (…)\nFor request methods other than HEAD, the server SHOULD generate a\n payload in the 300 response containing a list of representation\n metadata and URI reference(s) from which the user or user agent can\n choose the one most preferred. (…)\nNote: The original proposal for the 300 status code defined the\n URI header field as providing a list of alternative\n representations, such that it would be usable for 200, 300, and\n 406 responses and be transferred in responses to the HEAD method.\n However, lack of deployment and disagreement over syntax led to\n both URI and Alternates (a subsequent proposal) being dropped from\n this specification. It is possible to communicate the list using\n a set of Link header fields [RFC5988], each with a relationship of\n “alternate”, though deployment is a chicken-and-egg problem.\n— RFC 7231"},{"id":"text-107","heading":"Text","content":"To our knowledge, reactive negotiation has never been analyzed, used or suggested before.\nHere, apart from Lien relation header, we also suggest two more alternative implementation to solve\nthis issue and we will let the community to choose what is the more appropriate solution.\n10.4.1 The HTTP OPTIONS method\nThe server can describe the meta-data of a resource in the response body of the OPTIONS demande.\nIn fact, OPTIONS method has historically been used for getting information on methods supported on a specific resource.\nAccording to RFC 7231 this method should be used to\ndetermine the capabilities of the server for the targeted resource:"},{"id":"text-108","heading":"Text","content":"The OPTIONS method requests information about the communication\noptions available for the target resource, at either the origin\nserver or an intervening intermediary. This method allows a client\nto determine the options and/or requirements associated with a\nresource, or the capabilities of a server, without implying a\nresource action.\n— RFC 7231"},{"id":"text-109","heading":"Text","content":"The OPTIONS method could be used for the server to provide a list of available introspective MicroTypes\nand let the client choose what it thinks best.\nThe same RFC mentions that there isn’t any practical use of sending an OPTIONS request\nto the root url."},{"id":"text-110","heading":"Text","content":"An OPTIONS request with an asterisk (“*”) as the request-target\n(Section 5.3 of [RFC7230]) applies to the server in general rather\nthan to a specific resource. Since a server’s communication options\ntypically depend on the resource, the “*” request is only useful as a\n“ping” or “no-op” type of method; it does nothing beyond allowing the\nclient to test the capabilities of the server. For example, this can\nbe used to test a proxy for HTTP/1.1 conformance (or lack thereof).\n— RFC 7231"},{"id":"text-111","heading":"Text","content":"However, we feel that this is the perfect case for hosting an API’s discovery for available capabilities using\nreactive negotiation.\nWe could keep the / * for “ping” or “no-op” type of method as the RFC notes and have the root\n/ for listing all API’s capabilities through MicroTypes for all resources, as IATEOAS denotes.\nNow that we know how to fetch the MicroTypes that the server offers, we need to find\nan appropriate representation for it.\nOne option is to employ a common JSON format for describing each MicroType, its URL for introspection along\nwith the expected Media Type the response in the specified URL uses.\nFor instance if we would like to introspect resource /api/users/1 of an API we would get the following\ninformation by sending an OPTIONS request to the resource’s url."},{"id":"text-112","heading":"Text","content":""JSON-Schema": \n "url": "/api/users/1?microtype=json-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json"\n ,\n "RDF": \n "url": "/api/users/1?microtype=rdf",\n "method": "OPTIONS",\n "content-type": "application/rdf+xml"\n ,\n "JSON-LD": \n "url": "api/users/1?microtype=json-ld",\n "method": "OPTIONS",\n "content-type": "application/ld+json""},{"id":"text-113","heading":"Text","content":"The problem though is that such functionality (sending an OPTIONS demande à /api/users/1) must be described\nsomewhere so that the client knows where to look for it, possibly in the parent Media Type or using another MicroType.\nAn alternative option is to use the OPTIONS request in combination with the Lien header, as described later, that will announce\nthe MicroTypes availability. Such functionality should still be described somewhere as\nRFC 7231 only makes a suggestion for the Lien header usage.\nIt is our intention to advice the community to use this solution for the introspection process, without the Lien entête\nbut with a response body that describes the MicroTypes availability.\nThe structure and semantics of the response could be available in various serializations and formats and the clients could\nspecify their preference using the regular, proactive, HTTP negotiation flow of Media Types.\nAlthough, as we will see later, it comes at a cost, we feel that it’s the best among all three solutions presented here\nand the conceptual notion of OPTIONS method, as described by HTTP specs, matches very well with our intended use case.\nFurthermore, such process gives much more flexibility to append any additional information to the client, than\nan HTTP header.\n10.4.2. Well-known URIs and JSON Home\nRFC 5785 defines a pre-defined URI for accessing server’s various metadata:"},{"id":"text-114","heading":"Text","content":"It is increasingly common for Web-based protocols to require the\n discovery of policy or other information about a host (“site-wide\n metadata”) before making a request. For example, the Robots\n Exclusion Protocol http://www.robotstxt.org/ specifies a way for\n automated processes to obtain permission to access resources;\n likewise, the Platform for Privacy Preferences [W3C.REC-P3P-20020416]\n tells user-agents how to discover privacy policy beforehand. (…)\nWhen this happens, it is common to designate a “well-known location”\n for such data, so that it can be easily located. However, this\n approach has the drawback of risking collisions, both with other such\n designated “well-known locations” and with pre-existing resources.\nTo address this, this memo defines a path prefix in HTTP(S) URIs for\n these “well-known locations”, “/.well-known/”. Future specifications\n that need to define a resource for such site-wide metadata can\n register their use to avoid collisions and minimise impingement upon\n sites’ URI space.\n— RFC 5785"},{"id":"text-115","heading":"Text","content":"Using this specification, the server can register a well-known\nURI that is expected to be the first URI the client requests to introspect.\nTo that extend, a new draft spec is being developed, JSON Home\nthat defines such document structure that provides all the server resources and capabilities.\nRegardless if JSON Home is used, well-known URIs can provide a way to introspect only the\nserver-wide capabilities:\nIci, métadonnées would be a new well-known URI registry that either defined in the parent Media Type\nor defined by itself as a MicroType.\nThe spec does not provide a scheme for well-known URIs per resource or nested URI and this means\nthat we need to build something upon well-known URIs functionality in order to provide\nintrospection per resource.\nHow this will be achieved can be defined by the community, if used eventually,\nbut a possible implementation could be to pass\nthe desired resource URL as a query in the métadonnées well-known URI registry:"},{"id":"text-116","heading":"Text","content":"/.well-known/metadata?query=/api/users/1"},{"id":"text-117","heading":"Text","content":"Again as with HTTP OPTIONS, the server will either have to provide a representation\nof the available MicroTypes inside the response body of the well-known URI or use the Lien header.\nAlthough this solution could work, we feel that RFC 5785\nwas not designed to be used for such specific URIs but instead for more generic properties\nthat usually apply to the host itself.\nRegadless if HTTP OPTIONS or well-known URIs are used, Lien header, defined in RFC 5988,\nis an alternative way of publishing the available MicroTypes by the server,\nin a representation-agnostic way."},{"id":"text-118","heading":"Text","content":"A means of indicating the relationships between resources on the Web,\n as well as indicating the type of those relationships, has been\n available for some time in HTML [W3C.REC-html401-19991224], and more\n recently in Atom [RFC4287]. These mechanisms, although conceptually\n similar, are separately specified. However, links between resources\n need not be format specific; it can be useful to have typed links\n that are independent of their serialisation, especially when a\n resource has representations in multiple formats.\nTo this end, this document defines a framework for typed links that\n isn’t specific to a particular serialisation or application. Cela fait\n so by redefining the link relation registry established by Atom to\n have a broader domain, and adding to it the relations that are\n defined by HTML.\n— RFC 5988"},{"id":"text-119","heading":"Text","content":"As the next (draft) version of RFC 5988 notes:"},{"id":"text-120","heading":"Text","content":"a link published through Lien header can be viewed as a statement of the form\n“link context has a link relation type resource at link target, which has target attributes”.\n— rfc5988bis-07"},{"id":"text-121","heading":"Text","content":"As a result, this RFC provides us a representation-agnostic mechanism through which we can\nannounce link relations of the current visited URL, along with their relation types.\nFor instance, the following example"},{"id":"text-122","heading":"Text","content":"Link: ; rel="previous";\n title="previous chapter""},{"id":"text-123","heading":"Text","content":"would denote that that “chapter2” is previous to this resource in a logical\nnavigation path.\nNote that title is a target attribute or parameter to this link relation.\nIn the case of Introspected REST, we would use it to announce introspective MicroTypes related\nto the resource the client visits.\nBy exploiting the target attributes we would also like to specify the HTTP method and\noptionally the Media Type the client should expect in order to introspect\nthe given MicroType."},{"id":"text-124","heading":"Text","content":"Link: ; rel="microtype";\n method="options"; type="application/schema+json" name="json-schema",\n ; rel="microtype";\n method="options"; type="application/schema+json" name="rdf",\n ; rel="microtype";\n method="options"; type="application/schema+json" name="json-ld","},{"id":"text-125","heading":"Text","content":"Also related, Erik Wilde is working on an IETF draft, named Link Relation Types for Web Services\nthat defines a way to announce metadata of a resource through this mechanism.\nGiven that and also the fact that this solution has the advantage of solving the MicroTypes announcement\nin the HTTP protocol without being tied to a specific serialization, it’s easy to think that it’s the\nmost appropriate way to specify the MicroTypes supported on a specific resource.\nUnfortunately, this solution has a couple of drawbacks.\nFirst and foremost, the link header size is limited and if other headers of the response\nare already overloaded then the server might refuse to render the response to the client\nbut instead return an HTTP error possibly “413 Request Entity Too Large” or “414 Request-URI Too Long”\nalthough there isn’t an HTTP status code explicitly defined for such case.\nA possible solution to this could be Linkset: A Link Relation Type for Link Sets RFC proposal\n(a work also by Erik Wilde) but currently it’s in draft state.\nOnce published, a Linkset could group together a set of links and provide them to the client by reference.\nHowever Linksets don’t actually solve our issue because eventually the MicroTypes announcement would not\nbe solved in the HTTP level as a Linkset would have to provide a body format as well.\nAnother issue is that the server cannot specify a caching strategy for all links at once because there\nis no mechanism in HTTP which allows us to specify caching directives for specific headers only.\nAs a result, unless we used a Linkset which we can’t yet and would cancel any advantages that Lien header provides\ndue to the need of a response body,\nthe client would have to dereference all MicroTypes to figure out their caching properties.\nOn a side note, over the past few years, we have seen an explosion of link types\nused along with Lien header defined by RFC 5988.\nThe authors of Introspected REST are skeptical with this trend and feel that the Lien header should\nnot be overused.\nFor instance, having more than 5 links in the Lien header feels that something is wrong, probably too many things\nare defined in the protocol level whereas maybe they should be defined somewhere else.\nWe will let the community to decide if this approach is good for publishing MicroTypes but we would like to stress\nthe point that having a link in the HTTP level through Lien header might be better\nfor related resources that all clients would understand, which is not always the case in Introspected REST.\nThe API designer could add more MicroTypes, progressively, as the time passes and simultaneously,\nsome clients might not be interested or understand all MicroTypes of an Introspected REST.\nRequiring the client to receive all MicroType information for every data request is made\nwould probably be against the principles of Introspected REST.\n10.5. Considérations\n10.5.1 Diversifing from existing RFCs\nAlthough we have managed to apply Introspective REST to HTTP, a protocol that has been influenced so much\nby Roy’s REST model (and\nvice verca) this adaptation comes to a cost: we need to diversify from some RFCs specifications that we make use of.\nFortunately this diversification is relatively very small compared to the gains and all changes are\nbackwards compatible with existing deployed clients.\n10.5.1. HTTP OPTIONS responses are not cacheable\nFirst and most importantly, according to RFC 7231:"},{"id":"text-126","heading":"Text","content":"Responses to the OPTIONS method are not cacheable.\n— RFC 7231"},{"id":"text-127","heading":"Text","content":"This is the biggest breaking change to existing HTTP specs that Introspected REST applies.\nUnfortunately for a reason unknown to us, HTTP spec requires the clients to not cache responses of\nHTTP OPTIONS, essentially breaking out thinking of detached hypermedia and other metadata from plain data.\nIn practice though, adding cache headers in that HTTP method should be possible although\nlimitations by existing client implementations could exist.\nIf an API designer doesn’t want to break this part of HTTP spec then she should define the introspection\nprocess through the other suggested solutions, or come up with a new one.\nWhat is important though is that, as Introspected REST specifies, introspection process should be recognizably distinct from regular\ndata requests.\nThe authors of Introspected REST don’t see the reasoning of this constraint by HTTP spec and advise the community to investigate\nthe possibility of ignoring this limitation and proceed with HTTP OPTIONS introspection\nprocess that fits best to this architectural style.\nEventually, that would lead the IETF to completely drop it from HTTP spec.\nAlso, although the change itself could be considered as breaking because we alter a\nfunctionality that RFC 7231 specifies,\nthis alteration does not break existing clients but only the existing spec, because\nallowing clients to cache a response, which previously was not allowed, is backwards compatible.\n10.5.2. Media Type parameters must be very well defined beforehand\nAccording to RFC 6831 any Media Type parameters must be very well defined beforehand:"},{"id":"text-128","heading":"Text","content":"Media types MAY elect to use one or more media type parameters, or\n some parameters may be automatically made available to the media type\n by virtue of being a subtype of a content type that defines a set of\n parameters applicable to any of its subtypes. In either case, the\n names, values, and meanings of any parameters MUST be fully specified\n when a media type is registered in the standards tree, and SHOULD be\n specified as completely as possible when media types are registered\n in the vendor or personal trees."},{"id":"text-129","heading":"Text","content":"This goes against our concept of arbitrary number of autonomous MicroTypes that can be included by a parent Media Type parameters.\nHowever, we feel that given the sparse use of Media Types parameters, such breaking change will have a very small effect.\nThe authors of Introspected REST advice the community to investigate the possibility of pushing IETF to drop this requirement,\nor extend Media Type parameters with specialized parameters that can have arbitrary names.\n10.5.3. Media Types must function as actual media formats\nAnother thing that we differentiate is that according to same spec, each Media Type’s\nprimary functionality shoud be that of being media formats."},{"id":"text-130","heading":"Text","content":"Media types MUST function as actual media formats. Registration of\n things that are better thought of as a transfer encoding, as a\n charset, or as a collection of separate entities of another type, is\n not allowed. For example, although applications exist to decode the\n base64 transfer encoding [RFC2045], base64 cannot be registered as a\n media type.\nThis requirement applies regardless of the registration tree\n involved.\nRFC 6831"},{"id":"text-131","heading":"Text","content":"In our concept of MicroTypes, the parent Media Type acts as the base media format but has\nthe possibility to be extended by small components, MicroTypes.\nThese small components, which could be different in each request, define functionalities of different parts of the API\nand such functionality is not always in the context of media formats as RFC 6831 indicates.\n10.5.4. Mixed priorities are confusing\nOne more limitation comes from our MicroTypes definition through Media Type’s parameters and is related to priorities\nbetween MicroTypes and parent Media Types.\nImagine the client is sending the following to the server:"},{"id":"text-132","heading":"Text","content":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql; querying=jsonapi, application/vnd.api2+json;"},{"id":"text-133","heading":"Text","content":"Given this header, the client sets the priorities in the following order:"},{"id":"text-134","heading":"Text","content":"application/vnd.api+json with the following MicroTypes"},{"id":"text-135","heading":"Text","content":"pagination=simple-spec\nquerying=graphql Ou bien querying=jsonapi"},{"id":"text-136","heading":"Text","content":"application/vnd.api+json with the following MicroTypes"},{"id":"text-137","heading":"Text","content":"pagination=simple-spec\nquerying=jsonapi Ou bien querying=jsonapi"},{"id":"text-138","heading":"Text","content":"application/vnd.api2+json"},{"id":"text-139","heading":"Text","content":"But how can the client prioritize (3) choice over (2) ?\nHaving multilevel priorities is difficult in this context and could be only solved by sending 3 options to the server,\nessentially flatting and removing the MicroTypes priority scheme that we showed and falling back to the classic Media Type negotiation:"},{"id":"text-140","heading":"Text","content":"Accept: application/vnd.api+json; pagination=simple-spec; querying=graphql, application/vnd.api2+json, application/vnd.api+json; pagination=simple-spec; querying=jsonapi;"},{"id":"text-141","heading":"Text","content":"In our experience though, negotiation in HTTP is not used that extensively (although it should): clients\nare usually prepared before hand for one Media Type (and its MicroTypes in our context).\nThus, we don’t think this will be an issue in practice, at least initially, until community embraces Introspectiveness and new standards are created\nsolving these limitations.\nThis is also not a breaking change per-se but it’s good to have it in mind and possibly reconsider it or alter it\nwhen eventually patterns for MicroTypes and parent Media Types for Introspected REST APIs are settled down.\nTo our knowledge we haven’t broken any other HTTP-related specification for Introspected REST and the broken changes that\nwe had were very minor to our understanding, all of them being backwards-compatible to existing clients.\nGiven that the whole HTTP, related protocols and implementations, since its inception have always been based on proactive\nnegotiation we think that these changes are affordable for our new model.\nEven when they are not affordable we feel that there are alternative ways to mitigate those limitations.\nBut after all, IETF, W3C and related organizations usually are not preceding implementations but instead implementations\naffect and drive these specifications through the committees.\nIf IETF sees that people are using the specifications differently than these have been defined, they should update them\nor create new ones, as long as these don’t break the existing Internet infrastructure, which they definitely do not in our case.\n10.5.2. Performance considerations\nIntrospected REST adds some performance issues related to introspection process:\nthe client needs to first do a reconnaissance request to figure out what capabilities the server supports.\nThen for each capability that is described by a MicroType, the client might possibly need to send another request\nto retrieve the metadata of that MicroType.\nThis adds much more requests than regular REST APIs which would lead to increased latency until the client fetches\nor sends the actual resource.\nHowever, according to Introspected REST, the client can cache all this information using server’s caching headers,\nwhich could be different for each MicroType.\nIn that way, Introspected REST could possibly be more performant than regular REST because the client might have to actually\nrequest metadata very sparsely compared to actual data requests and given that the data responses will be much\nsmaller than REST’s equivalent responses (which would also hold all the necessary metadata), it should lead to better performance\nà long terme.\nWe should also note that Introspected REST is not ideal for all API designs and there could be cases that REST\nbecomes a better choice than Introspected REST.\nNevertheless, we feel that for most machine-to-machine communications Introspected REST is a better choice for all the advantages\nit offers and possibly more performant than REST.\n11. An Introspected REST API prototype in the world of HTTP and JSON\nIn the following we will describe the architecture of the Introspected REST APIs through\na proposed implementation.\nThe reader though should not confuse the proposed implementation details with the actual\narchitecture style.\nThis is by no means a complete Media Type, but just an example of the potential of Introspected REST.\nThe actual MicroTypes and Media Types will be created by the community.\nFor our solution, we will use JSON,\nJSON Schemas,\nJSON super schemas,\nJSON-LD\net problem+json\neach representing a different MicroType.\nBut the reader could apply the same ideas using any message format and spec.\nOur use case will be the same as the one in section 7.1, a miniature of yet another Social App.\nGiven that Introspected REST differs only in HATEOAS part of REST, the identification of the resources devrait be kept the same, namely:"},{"id":"text-142","heading":"Text","content":"Utilisateurs resource (/users):"},{"id":"text-143","heading":"Text","content":"List users (GET /users): Gets a collection of Utilisateur Ressources\nCreate a new user (/users): Creates a new Utilisateur with the specified attributes."},{"id":"text-144","heading":"Text","content":"Utilisateur resource (/users/id):"},{"id":"text-145","heading":"Text","content":"Get a user (GET /users/id): Gets the attributes of the specified Utilisateur\nUpdate a user PATCH /users/id: Updates a Utilisateur with the specified attributes\nDelete a user DELETE /users/id: Updates a Utilisateur with the specified attributes"},{"id":"text-146","heading":"Text","content":"Let’s assume that our parent Media Type is application/vnd.api+json.\n11.1. Isolating the actual data from metadata\nOur top priority is to offload the final response object from the metadata, like hypermedia.\nInstead, we will provide to the user only the data and possibly any runtime metadata.\nWhen the client manipulates a Utilisateur resource, the response should contain only the data:"},{"id":"text-147","heading":"Text","content":""user": \n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50"},{"id":"text-148","heading":"Text","content":"Similarly, a Utilisateurs resource will be a collection of Utilisateur resources:"},{"id":"text-149","heading":"Text","content":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ]"},{"id":"text-150","heading":"Text","content":"The actual format of the data could vary regarding the root element or possibly the place of the primary id.\nSuch details will be described by the Media Type.\nWhat is important here is that the data does not contain any metadata, apart from runtime metadata,\nthat we will describe later.\n11.2 Introspection Method\nFor introspection method we will use the HTTP OPTIONS, as described in 10.4.1,\nbut with the additional description of runtime MicroTypes, which in our case do\nhave some introspective content for the client to fetch.\nThe specific semantics of this document will be described in the parent Media Type,\nbut it would look like this:"},{"id":"text-151","heading":"Text","content":""micro-types": \n "runtime": \n "pagination": \n "url": "/api/users/1?microtype=pagination",\n "method": "OPTIONS",\n "content-type": "application/simple-pagination+json",\n "priority": "1.0"\n ,\n "errors": \n "url": "/api/users/1?microtype=errors",\n "method": "OPTIONS",\n "content-type": "application/simple-errors+json",\n "priority": "1.0"\n \n ,\n "introspective": \n "json-schema": \n "url": "/api/users/1?microtype=json-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json",\n "priority": "0.8"\n ,\n "json-hyper-schema": \n "url": "/api/users/1?microtype=json-hyper-schema",\n "method": "OPTIONS",\n "content-type": "application/schema+json",\n "priority": "0.8"\n ,\n "json-ld": \n "url": "/api/users/1?microtype=json-ld",\n "method": "OPTIONS",\n "content-type": "application/ld+json",\n "priority": "0.5"\n ,\n "simple-description": \n "url": "/api/users/1?microtype=simple-description",\n "method": "OPTIONS",\n "content-type": "application/json",\n "priority": "0.2"\n \n \n ,\n "documentation": \n "url": "/documentation#user",\n "method": "OBTENIR",\n "content-type": "text/html""},{"id":"text-152","heading":"Text","content":"Each entry describes the url which the client can access it, the HTTP method\nthe client should use along with the Media Type of the expected response.\nFinalement, le priorité number specifies the preceding order of each MicroType\nin case a functionality is described by one or more MicroTypes.\nNote that the Media Type of the introspective content will be described\nby the MicroType the client tries to access.\nAs a result, if a client doesn’t recognize a MicroType, it wouldn’t try to access\nit anyway.\n11.2. Runtime Metadata\nIt goes without saying that when a client requests a collection of resources,\nit expects some kind of pagination with it.\nFor pagination MicroType we have a number of different options.\nOne option is to use the Lien header and define the links there, in a representation-agnostic way.\nBut given that our application is intended to powerful clients that would also parse the JSON body\nwe wouldn’t gain much, possibly we would make things even more complex for them.\nAnother possibility, with some inspiration from JSONAPI, is to use the premier, dernier, prev et suivant spécifier\nthe first, last, previous and next page respectively."},{"id":"text-153","heading":"Text","content":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ],\n "meta":\n "self":"/api/users?page=2&per_page=10&offset=0",\n "first":"/api/users?page=1&per_page=10&offset=0",\n "prev":"/api/users?page=1&per_page=10&offset=0",\n "next":"/api/users?page=2&per_page=10&offset=0",\n "last":"/api/users?page=9&per_page=10&offset=0""},{"id":"text-154","heading":"Text","content":"A different approach is to just specify\nla page, per_page et décalage to the client and also provide a URI template to\nuse with those values to access any page."},{"id":"text-155","heading":"Text","content":"{\n "users": [{[{[[\n "id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count": 50\n , \n "id":"9124",\n "email": "[email protected]",\n "name": "Robert Clarsson",\n "birth_date": "1940-11-10",\n "created-at": "2016-10-06T16:01:24Z",\n "microposts-count": 17,\n ],\n "meta": \n "page": 2,\n "per_page": dix,\n "offset": 0"},{"id":"text-156","heading":"Text","content":"We could provide the URI template when introspecting the pagination MicroType:"},{"id":"text-157","heading":"Text","content":""link": "/api/resource?page, per_page, offset""},{"id":"text-158","heading":"Text","content":"Of course, the MicroType spec would specify how the client should parse and determine\nthe pagination links from this introspective content.\nIn that way, we don’t treat the clients as stupid but smart enough to understand\nwhat they need to do on their part to get what they want.\nWhich is the best solution? It depends, and that’s why we should embrace MicroTypes.\nle Lien header-based solution is representation-agnostic and could benefit some clients\nthat don’t deal much with the content but in practice such clients are very rare, especially in our use case.\nThe second solution would limit the client application developer if she wanted to have a link\nof a specific page, while the last solution would limit the API designer to avoid\nhaving the number of total pages in the response, because it could be a huge cost to the database level.\nIn any case, Introspected REST doesn’t restrict us to specify two or more alternative MicroTypes for the same API\nfonctionnalité, like pagination.\n11.2.2 The Errors MicroType\nWhen the API is supposed to return an unexpected response to the user, like a 4xx or 5xx error,\nthe response will have a different structure than the resource that the client requested.\nUsually the semantics of an error respond are defined in the API’s Media Type but we will use the newly-published RFC 7807 (Problem Details for HTTP APIs),\nwhich defines the problem+json Media Type for JSON HTTP APIs.\nTo give an example how the response will seem when following this RFC,\nimagine that when updating a User object, the application developer might wrongly send an invalid birth_date.\nThen the application should respond with the following structure:"},{"id":"text-159","heading":"Text","content":""Titre": "The birthdate has an invalid format.",\n "details": "The birthdate must be in the format of 1985-04-12T23:20:50.52Z.",\n "status": 422"},{"id":"text-160","heading":"Text","content":"If you inspect the spec you will notice that the spec limits us by omitting specifying a way to associate an error message with a specific resource attribute.\nAs a result, we can only specify the falsy attribute in the title or details attribute of the error object, which are human-targeted,\nand thus informing only the end user and not the client.\nWe could add extension members, as the spec suggests, to customize the error object in our needs but the final response object wouldn’t be\nself-descriptive, unless we customly extended it.\nThe good thing though is that normally such errors should be caught on the client-side by the introspected MicroTypes for the resource structure,\nwhich in our use case are the schema validations from the JSON Schema MicroType.\nThe error object could be used for more advanced errors, like the following:"},{"id":"text-161","heading":"Text","content":""Titre": "Transaction failed",\n "details": "The remaining amount of virtual coins in your account is not enough for this purchase",\n "status": 403"},{"id":"text-162","heading":"Text","content":"Another thing that we should take care is the fact that this RFC requires returning a different Media Type than the one used by the API.\nIn theory the API’s Media Type explain how the errors work using the same semantics as defined in problem+json RFC but the RFC\nsuggests using application/problem+json for Media Type."},{"id":"text-163","heading":"Text","content":"The data model for problem details is a JSON [RFC7159] object; quand\nformatted as a JSON document, it uses the “application/problem+json”\nmedia type.\n— RFC 7807\nHowever in order for this to work the client needs to negotiate it and accept this Media Type,\notherwise we have a gap in the client-server communication.\nThe client can’t be asking for the API’s Media Type and unexpectedly receive the application/problem+json\nMedia Type."},{"id":"text-164","heading":"Text","content":"In HTTP that would be achieved using the Acceptez header, which could look like that:"},{"id":"text-165","heading":"Text","content":"Accept: application/vnd.api+json, application/problem+json"},{"id":"text-166","heading":"Text","content":"But that reminds us the concept of (runtime) MicroTypes, right?\nEven the negotiation looks very similar.\nTo that extend, creating a wrapper MicroType shim around this Media Type, that other API designers\ncan also use, should be effortless.\nTo take one step further, given that such error information is crucial for the user to understand why her action is not advancing,\nwe feel that the client should be able to négocier the errors MicroType, that is, the information and structure of the\nreturned errors object.\nSome clients might need the most basic error information and use only the HTTP status code, other clients might\nbe interested in as much possible information available in order to show it to the user.\nFor instance, the client might show preference to another problems Media Type before falling back to problem+jsoncomme\nseen in the following Accept header example:"},{"id":"text-167","heading":"Text","content":"Accept: application/vnd.api+json, errors=problem/extensive+json, errors=problem+json;"},{"id":"text-168","heading":"Text","content":"11.3. Introspective Metadata\nWe will describe our APIs capabilities by mixing together different MicroTypes targeted each one for a specific capability\nof our API, following the Single Responsibility Principle.\nThe client will be able to retrieve the information of each metadata MicroType by introspecting the resource.\n11.3.1. Structural metadata\nOne of the most important things for a client to know is the expected structure of the request/response resource object\nalong with information on the data types.\nFor that we will use JSON Schemas, a powerful spec that enables you to describe and validate your JSON data.\nGiven that this specification has been published using the RFC method and taking into account its popularity,\nit is very probable that there est\nan implementation for that MicroType for the client’s environment.\nAlso, a cool side effect of having the structure definition of the resource as a MicroType available through resource’s introspection,\nis that the client can use this information to first validate the object before sending it over the wire to the server.\n11.3.1.1. User resource"},{"id":"text-169","heading":"Text","content":"{\n "$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/user.json",\n "Propriétés":{\n "user":\n "type":"objet",\n "Propriétés":\n "id":\n "maxLength":64,\n "type":"chaîne"\n ,\n "email":\n "maxLength":255,\n "type":"chaîne",\n "format":"email"\n ,\n "name":\n "maxLength":255,\n "type":[[[["null", "chaîne"]\n ,\n "birth_date":\n "type":"chaîne",\n "pattern":"^[0-9]4-[0-9]2-[0-9]2$"\n ,\n "created_at":\n "maxLength":255,\n "type":"chaîne",\n "format":"date-time"\n ,\n "microposts_count":\n "type":"entier"\n \n ,\n "Champs obligatoires":[[[[\n "id",\n "email",\n "name",\n "birth_date",\n "created_at",\n "microposts_count"\n ]\n \n },\n "Champs obligatoires":[[[[\n "user"\n ],\n "type":"objet"\n}"},{"id":"text-170","heading":"Text","content":"11.3.1.2. Users resource\nNote that the Users resource is just a collection of User object and as a result\nit references the User schema."},{"id":"text-171","heading":"Text","content":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/users.json",\n "Propriétés":\n "users":\n "type": "array",\n "$href": "https://example.com/user.json#/properties/user"\n ,\n "meta": \n "type":"objet",\n "page": \n "type": "entier",\n "default": 0,\n "le minimum": 0,\n "$ref": "#/definitions/extra"\n ,\n "per_page": \n "type": "entier",\n "le minimum": 1,\n "maximum": 100,\n "default": 50\n ,\n "offset": \n "type": "entier",\n "le minimum": 0,\n "default": 0\n ,\n "Champs obligatoires":[[[[\n "page",\n "per_page",\n "offset"\n ],\n \n ,\n "Champs obligatoires":[[[[\n "users",\n "meta"\n ],\n "type":"objet""},{"id":"text-172","heading":"Text","content":"11.3.1.3. Request Response inconsistency\nAlthough here we have the same object semantics for request and response object, in theory these could be different.\nIf that’s the case, we should denote each object in the response parented under\ndistinct JSON attributes (like accepte/produit ou accepte/résultats).\n11.3.2. Hypermedia metadata\nFor the Hypermedia part we will use JSON Hyper Schemas.\nSpecifically we will use the draft V4 of JSON Hyper Schemas as the\nnext versions (V5, V6) are targeted to hypermedia APIs that\nare HTML-equivalents. For instance, there is no way we can define a méthode attribute, restricting us to OBTENIR et POSTER\ndepending whether there is a body to send or not.\nIn the Introspected REST terminology, V5 and V6\nprovide hypermedia semantics only for forms and not actions.\nResource schemas defined in the previous section are referenced by the following Hyper Schemas, in order to avoid\nduplication of our metadata.\nSuch functionality would have to be described by both MicroTypes.\n11.3.2.1. User resource"},{"id":"text-173","heading":"Text","content":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/user-links.json",\n "Propriétés":\n "$href": "https://example.com/user.json#/properties"\n ,\n "links": [[[[\n \n "rel": "microposts",\n "href": "/microposts?user=userId&page=page&per_page=per_page&offset=offset",\n "hrefSchema": \n "allOf": [[[[\n \n "$ref": "https://example.com/users.json#/properties/meta"\n ,\n \n "$ref": "https://example.com/users.json#/properties/user/id"\n ,\n ]\n \n ,\n \n "rel": "update-user",\n "href": "/users",\n "method": "PATCH",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n ,\n \n "rel": "delete-user",\n "href": "/users",\n "method": "DELETE",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n \n ]"},{"id":"text-174","heading":"Text","content":"11.3.2.2. Users resource"},{"id":"text-175","heading":"Text","content":""$schema":"https://json-schema.org/draft-04/schema#",\n "$id":"https://example.com/users-links.json",\n "Propriétés":\n "$href": "https://example.com/users.json#/properties"\n ,\n "links": [[[[\n \n "rel": "self",\n "href": "/users?page=page&per_page=per_page&offset=offset",\n "hrefSchema": \n "$ref": "https://example.com/users.json#/properties/meta"\n \n ,\n \n "rel": "create-user",\n "href": "/users",\n "method": "POST",\n "targetSchema": \n "$ref": "https://example.com/user.json"\n \n \n ]"},{"id":"text-176","heading":"Text","content":"Notice that we also define here the pagination, by referencing parts of the user’s méta objet.\nOur strategy is duplicate common functionality in MicroTypes, wherever we can, in order to help\nour clients. Possibly not all clients will be programmed for all our MicroTypes, especially if we\nrelease them progressively.\n11.3.4. Descriptions metadata\nFor human-targeted information, we could use a custom MicroType that describes each attribute of the response object.\nNotez que this information must not be required to parse and understand the API but to use the API data on our application domain.\nFor instance, understanding that when updating the email attribute an email is triggered to inform the user for the change,\nis not part of the API client responsibility but it’s vital for the application developer to to know what to expect from it."},{"id":"text-177","heading":"Text","content":""user": \n "id": \n "Titre": "The identifier of the resource.",\n "la description": [[[[\n "This identifier should not be exposed to the user, to avoid any confusions."\n ]\n ,\n "email": \n "Titre": "The primary email of the user's account",\n "la description": [[[[\n "The email is used for any transactional email.",\n "Also, the same email is used when user authenticates to the system.",\n "Please note that whenever you update the email, user receives an automated email describing the change"\n ]\n ,\n "name": \n "Titre": "The user's full name (first and last name concatenated)",\n "la description": [[[[\n "This field could be empty or null.",\n "If so, the application should show the email instead for the user's name."\n ]\n ,\n "birth_date": \n "Titre": "The date of birth of the user",\n "la description": []\n ,\n "microposts_count": \n "Titre": "The number of published microposts the user has.",\n "la description": [[[[\n "Please note that due to caching this number could have a small delay to reflect the actual number",\n "The application should either inform the user about that or make sure it manually updates the microposts counter after publishing/deleting a micropost after publishing/deleting a micropost."\n ]"},{"id":"text-178","heading":"Text","content":"This metadata will be used for the documentation generation, as we will see in section 11.7.\n11.3.5. The case of a non-compatible spec for introspection: Linked Data metadata using JSON-LD\nFor denoting the semantic meaning of each attribute of our resources we will employ JSON-LD.\nIt should be noted that JSON-LD spec was developed with the goal to require as little effort as possible from developers\nto transform their existing JSON to JSON-LD but also to not require breaking changes to your\nexisting API, which makes it backwards compatible with any current deployed API.\nThis conflicts with our design of introspection because having contexts without the data would break the spec.\nAs a result we have the following 2 options.\n11.3.5.1. Extending spec by creating a Shim MicroType\nOur first option is to create a wrapper shim MicroType that defines how the spec should work\nfor the clients to parse and understand the data, with the least possible changes.\nA naive shim, that we show here, would output the context information in the introspected process.\nThen the client should match this information in combination with the runtime data.\n11.3.3.1. User resource"},{"id":"text-179","heading":"Text","content":""@context": \n "@vocab": "https://schema.org/",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul"},{"id":"text-180","heading":"Text","content":"11.3.3.2. Users resource"},{"id":"text-181","heading":"Text","content":""@context": \n "@vocab": "https://schema.org/",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n ,\n "@graph": [[[[\n \n "@type": "La personne"\n \n ]"},{"id":"text-182","heading":"Text","content":"11.3.5.2. Considering it as runtime metadata\nOur second option is to exploit the IATEOAS principles regarding runtime metadata\nand append them inside the response by considering them as object-specific runtime metadata.\nHowever, we feel that such decision should be taken only if nothing else is possible,\ngiven that in Introspected REST data and metadata should be distinctively separated.\n11.7. Automating the documentation generation\nThe documentation of our API should be a dedicated page under the API’s URL namespace (i.e. /api),\nby returning a regular web page, targeted to humans and not machines.\nThe technical details is out of the scope of this prototype example but we\ncan’t stress enough that the generated documentation should mostly use information from MicroTypes available for the machines,\nprogrammatically wrapped in a human-friendly format.\n12.1. GraphQL\nGraphQL is a data query language that was created by Facebook and released to the public\nin 2015.\nThe specification of the query language is not tied to the protocol used\nunderneath or the message format, although HTTP in combination with JSON is usually used.\nWhat is different about GraphQL is that it makes the client’s requirements and performance\nas a top priority, regardless of the internal implementation of the data layer in the server.\nAs a result, front-end engineers tend to love it due to its expressiveness that\nusually is not found in REST APIs.\nFor instance, retrieving a Utilisateur object with a subset of it’s attributes, along\nwith some microposts ordered by creation date, is very easy, given that the server\nimplementation support those filters:"},{"id":"text-183","heading":"Text","content":"utilisateur(identifiant: "1") \n prénom\n email\n birth_date\n microposts (limite: dix, orderBy: created_at)\n Titre\n \n \n}"},{"id":"text-184","heading":"Text","content":"The query not only specifies what the client wants to retrieve but also it specifies\nthe structure the response should have.\nAlso, GraphQL supports an introspection process that clients can use in order to figure\nout the available fields of each resource along with other useful information, like\ndata types, the available operations those resource support (mutations in GraphQL terminology) etc.\nGraphQL solves common issues in networked APIs in a radical, unique way.\nFacebook engineers figured out that instead of trying to adapt\nexisting Internet infrastructure and protocols to their needs, they designed\na query language that solves their problems and use HTTP as a dumb pipe to do the hard work of\ncommunicating both queries and data.\nIn terms of REST principles, GraphQL responses are both evolvable and self-descriptive, as GraphQL’s\nintrospection is very powerful allowing the clients to learn anything that is needed\nabout the resources.\nHowever, we feel that GraphQL does have some costs and it’s not a solution that any\nbusiness can apply.\nFirst, GraphQL doesn’t play well with the existing HTTP infrastructure.\nFor instance, most GraphQL implementations, use a single endpoint with the same\nHTTP method, POSTER, for the client-server communication.\nAs a result, the specification cannot take advantage of existing HTTP protocols\nand mechanisms but instead has to re-invent the wheel on some of them, like caching.\nAlso, adding GraphQL to an existing service has huge costs.\nAlthough there are libraries for most languages and frameworks that facilitate the development of\nGraphQL API, this is not always the case.\nBut apart from that, the server engineer must take full responsibility for supporting all\nkind of queries the client might need and at the same time these queries need to be efficient and scalable.\nWhen we can know in advance what are the limits of a query, we are able to optimize for it,\nhowever, with GraphQL, a client can send any query using any of the all the possible resources and structure them\nin a way that for the server is random.\nIn such cases, it’s impractical to optimize beforehand and solving scaling issue becomes\na real challenge that possibly only companies with huge amount of resources can really afford.\nAnd again, as with existing Media Types design, GraphQL creates a closed silo in our API and differentiating from the existing\nspec is nearly impossible.\nFor instance, if we need to support an additional data type, it’s impossible\nbecause we are dependent to the existing libraries and creating our own GraphQL library would require too much time.\nBut even if that was solved, a possible modification in the current spec would probably break most existing clients.\nWe feel that a MicroType-based architecture is more powerful than a specification that, although powerful,\nlimits the users to its semantics.\nThe fact that REST API designers haven’t treated very well front-end\nengineers in the past, in combination with the complexity a modern\nREST API could have, has given a lot of space to GraphQL to rise as one of the most prominent\nAPI designs.\nAlthough GraphQL is a great asset to have it around, we don’t think that it’s practical for\nall API cases, but instead it mostly suits best big companies that can afford the costs.\nThe API designer must balance the trade off between the cost of development and the\nclient’s affordances.\nWith Introspected REST and a number of powerful MicroTypes it is possible to replicate the existing GraphQL\nspecification and even leverage existing HTTP infrastructure.\nIn fact, we feel that Introspected REST is far more powerful than GraphQL:\nnot only it gives you the ability to balance the costs of implementation and client performance,\nbut also it can support multiple, different, querying specs for different classes of clients,\nall these by leveraging the existing HTTP infrastructure.\n12.2. Linked Data and Semantic Web\nLinked data and semantic web has been trying to solve the problem of mutual understanding\nbetween machines many years now.\nUsing a pre-defined vocabulary, machines can determine the type of a resource, like if\nit’s a person, an employee, an athlete or\neven the types of each attribute of a resource, like a name, an email etc.\nIt is a step close to have self-descriptive APIs that machines can understand and process.\nFor instance, using JSON-LD as we saw earlier, we can specify all attributes of a Utilisateur resource:"},{"id":"text-185","heading":"Text","content":""user": \n "@context": \n "@vocab": "https://schema.org/",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n ,\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50"},{"id":"text-186","heading":"Text","content":"Moreover, modern specifications like JSON-LD allow us to omit\nthe definitions from the response’s data and instead provide only a link to\na publicly accessible directory that a machine can déréférence,\nsimilarly to the introspection method of Introspected REST.\nThe resource ony needs to have the vocab attribute inside JSON-LD’s le contexte."},{"id":"text-187","heading":"Text","content":""user": \n "@context": \n "@vocab": "https://example.com/my-custom-schema/"\n ,\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50"},{"id":"text-188","heading":"Text","content":"The idea of semantic web can be found even in real life.\nIn an example taken by Donald Norman, and\noften quoted by Mike Amundsen’s talks,\nin real life when we see a door, we know instantly how it opens because we have associated\nthe design of the door with its opening mechanism:\nif a door has a bar across it then we push while if there is a little handle in the door then we pull.\nWhile semantic web allow us to associate resources in the web with entities that hold\nmetadata and have specific properties, in Introspected REST we ask the door itself how its mechanism works:\nusing the door’s metadata we can learn how to open any door and eventually we can even\nopen doors whose opening mechanism we have never seen before.\nIn any case, in Introspected REST we embrace semantic web by employing the necessary MicroTypes\nand we don’t really feel that this work is related to Introspected REST in a competing sense\nbut instead, both concepts could complement each other.\nIn fact, we feel that using linked data is just great and API designers should employ it more often.\n12.2.1 Hydra\nTo that extend, Markus Lantaler developed Hydra, which not only allows us to associate\ncommon resources and attributes with their representation but also RESTful hypermedia\nconcepts on them, like actions (called operations), links, status codes etc.\nSo again in our use case, we can specify some actions using Hydra:"},{"id":"text-189","heading":"Text","content":""@context": [[[[\n "http://www.w3.org/ns/hydra/core",\n \n "@vocab": "https://example.com/my-custom-user-vocab",\n "@type": "La personne",\n "birth_date": "birthDate",\n "created_at": "dateCreated",\n "microposts_count": nul\n \n ],\n "@id":"685",\n "email":"[email protected]",\n "name":"Filippos Vasilakis",\n "birth_date": "1988-12-12",\n "created_at": "2014-01-06T20:46:55Z",\n "microposts_count":50,\n "operation": \n "@type": "UpdateUser",\n "method": "PATCH",\n "expects": \n "@id": "https://example.com/my-custom-user-vocab",\n "supportedProperty": [[[[\n \n "@type": "email",\n "property": "email",\n "Champs obligatoires": faux\n ,\n \n "@type": "name",\n "property": "name",\n "Champs obligatoires": faux\n ,\n \n "@type": "birthDate",\n "property": "birth_date",\n "Champs obligatoires": faux\n \n ]"},{"id":"text-190","heading":"Text","content":"Again, Hydra’s-specific content, like operations, can become dereferencable thus\nmaking response’s load much smaller, although this is not a requirement as in\nIntrospected REST.\nAlthough we support initiatives that allow API designers to serve metadata on the side,\nlike Hydra does with dereferencable content, we can’t miss the fact that Hydra\nhas become a very complex specification and still it’s type system is a weak one.\nWe firmly believe that MicroTypes for actions (Hydra’s equivalent to operations)\nwill be much more powerful than hydra’s semantics of Champs obligatoires, en écriture, lisible,\nand soon an API designer will be able to choose one MicroType from the same class of\nMicroTypes, like data types, that fits best for her.\nSpecifications that try to define everything in one place, like Hydra does, limit\nthe API designers a lot and eventually such specs\ndeliver an mediocre set of choices to choose from.\nIn any case, we feel that Hydra spec is one of the few API specs that significantly\ndiffers from the conventional API specs and can provide almost completely self descriptive\nles réponses, an unfortunately rare key property of modern APIs.\n12.3. The ‘profile’ Link Relation Type\nSimilar to the profile media type parameter\nthat Toby A. Inkster had proposed in 2009, Erik Wilde suggested a profiling mechanism\nof the underlying Media Type through the HTTP Link header, that was later\npublished as RFC 6906."},{"id":"text-191","heading":"Text","content":"A profile is defined not to alter the\n semantics of the resource representation itself, but to allow clients\n to learn about additional semantics (constraints, conventions,\n extensions) that are associated with the resource representation, in\n addition to those defined by the media type and possibly other\n mechanisms.\n— RFC 6906"},{"id":"text-192","heading":"Text","content":"Essentially, the profile parameter, given that the client understands it, would define Additionnel semantics of\nthe response’s representation that are not defined through the Media Type used.\nThe information for the additional semantics would be found in all responses regardless the client but only\nthe “smarter” clients would be able to parse, understand and use this information whereas the rest would just ignore it.\nThis link relation type is similar to our work of MicroTypes but unfortunately fails to advocate towards reusable profiles."},{"id":"text-193","heading":"Text","content":"While this specification\n associates profiles with resource representations, creators and users\n of profiles MAY define and manage them in a way that allows them to\n be used across media types; thus, they could be associated with a\n resource, independent of their representations (i.e., using the same\n profile URI for different media types). However, such a design is\n outside of the scope of this specification, and clients SHOULD treat\n profiles as being associated with a resource representation.\n— RFC 6906"},{"id":"text-194","heading":"Text","content":"By having profiles attached to specific Media Types results in much less adoptability and flexibility and fails to signal the\nactual practicability of such architecture.\nHowever, if profiles take the conceptual form of independent MicroTypes, then the clients can negotiate for those and eventually choose\nthe one that fits best.\nAlthough the negotiation part is skipped from the RFC, we feel that such works are towards the right direction that will allow us\nto build evolvable, self-described APIs.\n12.4. JSON Home\nNote that JSON Home is still in a draft state.\nJSON home is a draft specification\nthat defines a “home document” format for non-browser HTTP clients to first request in order to discover\nthe server’s capabilities that it support.\nSpecifically, the document specifies semantics to describe the API itself (like author, documentation link etc)\nalong with its resources.\nFor each resource, the document can provide a link for the client to access it directly (instead of\nfiguring out the link using REST state transitions) and more information, mostly hints, like\npermitted methods, media types etc.\nIt should be noted that JSON Home it’s one of the few specifications along with RFC 7807 (Problem Details for HTTP APIs)\nand possibly Linksets that\nbecause of their semantics and specifications, they slide away from Roy’s REST model and\nacknowledge the distinction between\nbrowser-based clients that are driven by real humans, and non-browser, machine based-clients and suggests\nthat the latter should be treated differently.\nAs the draft notes the benefits of using such a home document are multifold:"},{"id":"text-195","heading":"Text","content":"o Extensibility – Because new server capabilities can be expressed\n as link relations, new features can be layered in without\n introducing a new API version; clients will discover them in the\n home document. This promotes loose coupling between clients and\n les serveurs.\no Evolvability – Likewise, interfaces can change gradually by\n introducing a new link relation and/or format while still\n supporting the old ones.\no Customisation – Home documents can be tailored for the client,\n allowing different classes of service or different client\n permissions to be exposed naturally.\no Flexible deployment – Since URLs aren’t baked into documentation,\n the server can choose what URLs to use for a given service.\no API mixing – Likewise, more than one API can be deployed on a\n given server, without fear of collisions.\n— Home Documents for HTTP APIs, draft 06"},{"id":"text-196","heading":"Text","content":"Although we can instantly see the benefits of such structure, we believe that a specification like JSON Home\nis very weak. Specifically, it is tied to JSON message format which, although very popular, could possibly be\ninappropriate in some use cases.\nInstead, a better idea would be to define the necessary attributes and semantics that a Home document\nshould provide and then let the API designer to choose if these will be implemented in JSON, XML or binary format.\nSuch architecture would be more robust and would give more options to an API designer.\nSecondly, the document resource hints are very abstract and generic that probably are not sufficient\nfor the client to parse them without some documentation.\nOur work makes use of MicroTypes that allows the API designer to offload such information\nto more specific formats, possible duplicated in multiple specs to support as many as possible\nclients, but also to let the clients select the most appropriate MicroType(s) for them.\nWe firmly believe that a MicroType-based architecture is much more powerful than a simple,\nsemantically identical for all APIs, JSON-specific, home document.\nHowever we can’t neglect the fact that influencing engineers are finally recognizing the\ndissimilarity of browser-based, driven by humans clients and machine-based clients.\nIn fact, carving our infrastructure for machine-based clients to be similar with human-driven clients we\nunderestimate their capabilities: machines can be much more powerful and smart than humans.\n12.5. RESTful API Description Languages\nOver the past years, there has been a trend on creating API documentation through specialized tools, like OpenAPI specification (ex. Swagger).\nAs we have already noted, in a REST API documentation, in the sense of offline contracts,\nshouldn’t even exist and thus such approach is fundamentally wrong.\nBy giving so much weight on the documentation but at the same time treating it as something different, separated from the code\nleads to inconsistencies between the actual API and the API description.\nThose tools have been improved so much lately that now allow us to write the documentation and let them generate\nthe basis of our code, depending on our language/framework, which could fix the inconsistencies issues.\nUnfortunately though, such approach leads to an RPC design instead of a hypermedia-based system.\nWe believe that API designers are limited by marrying these tools.\nThe tools themselves have limitations,\nbut also, having tools that aim to provide all-in-one to the API designer is against our philosophy: tools should do one thing and do it well.\n12.6. API directories\nAnother trend for APIs is to register them in an online service, called API dictionary and possible push there the API documentation as well.\nWe feel that this is not a very helpful structure. APIs should be discoverable by themselves without using centralized services.\nThe API’s conceptual root url should provide everything that is needed, and using already published protocols\nlike WebFinger, which builds upon Well-Known Uniform Resource Identifiers RFC\nand can give API information for client bootstraping.\n13. Conclusion"},{"id":"text-197","heading":"Text","content":"The best software architecture “knows” what changes often and makes that easy.\n— Paul Clements"},{"id":"text-198","heading":"Text","content":"Is it the API spec designers to blame for creating non self-descriptive REST specifications or did they make a deliberate choice\nto avoid fully support the HATEOAS constraint of REST and instead delegate such information to documentation?\nIn the research of a fully REST API, we determined that REST is complex and\ninflexible.\nMoreover, its adaptation in HTTP goes through the mechanism of Media Types\nwhich specifies the whole API vocabulary in a sole place\nwhile HATEOAS need to bear the brunt of communicating to the client the available\ncapabilities of the server, based on Media Type’s vocabulary,\nfor each resource.\nThe result is very complex API responses that tangle together hypermedia with data making development a real\nchallenge for both the client and the server.\nOur new model, Introspected REST, which solves most of REST issues, steps on Roy’s initial model\nbut takes a different path regarding hypermedia. It requires the server to deliver only\ndata when a resource is requested, stripping out any HATEOAS-related information and instead deliver\nthe hypermedia on the side whenever a client needs it.\nHowever, Introspected REST goes beyond conventional hypermedia by supporting more classes of metadata, other\nthan hypermedia, through our concept of MicroTypes which act as small reusable components of API\nfonctionnalité.\nMicroTypes are not intended to be used only for allowing the client to derive the application state\nat runtime. They also make the clients smarter by allowing them to take an active role\nin the client-server communication\nwhile enabling them to provide essential feedback to the application layer.\nWe firmly believe that Introspected REST is the key to evolvable services of the future that are accessed by unmanned clients\nwith a lifespan of decades.\nOur model allows the API designers to fine-tune the flexibility and extensibility of the API to their needs,\neven progressively or asymmetrically for different classes of clients.\nChoosing between REST or GraphQL won’t be necessary as our model can support both styles simultaneously,\nusing multiple sets of MicroTypes."},{"id":"text-199","heading":"Text","content":"Click to rate this post!\n \n [Total: 0 Average: 0]"}],"media":{"primary_image":""},"relations":[{"rel":"canonical","href":"https://tutos-gameserver.fr/2019/05/03/introspected-rest-une-alternative-a-rest-et-graphql-serveur-dimpression/"},{"rel":"alternate","href":"https://tutos-gameserver.fr/2019/05/03/introspected-rest-une-alternative-a-rest-et-graphql-serveur-dimpression/llm","type":"text/html"},{"rel":"alternate","href":"https://tutos-gameserver.fr/2019/05/03/introspected-rest-une-alternative-a-rest-et-graphql-serveur-dimpression/llm.json","type":"application/json"},{"rel":"llm-manifest","href":"https://tutos-gameserver.fr/llm-endpoints-manifest.json","type":"application/json"}],"http_headers":{"X-LLM-Friendly":"1","X-LLM-Schema":"1.1.0","Content-Security-Policy":"default-src 'none'; img-src * data:; style-src 'unsafe-inline'"},"license":"CC BY-ND 4.0","attribution_required":true,"allow_cors":false}