L'API REST doit être basée sur l'hypertexte

"Et vous l'avez cru?" Le médiateur du sabot a dit avec reproche. "Eh bien, qu'en pensez-vous, aurais-je pris ces poids sans votre permission?"

"Alors tu as pris les poids?" Cria Ostap. - Pourquoi?

- Panikovsky a dit qu'ils étaient en or.

Ostap regarda Panikovsky. Ce n'est que maintenant qu'il a remarqué que sous sa veste, il n'y avait pas plus de cinquante dollars de devant de chemise et qu'à partir de là, le regard nu de Dieu regardait la lumière du jour. Sans un mot, le grand combinateur est tombé sur une chaise. Il trembla, attrapant ses mains en l'air. Puis des grondements volcaniques jaillirent de sa gorge, des larmes coulèrent de ses yeux, et des rires, qui affectèrent toute la fatigue de la nuit, toute la déception de la lutte contre Koreiko, si pathétiquement parodiée par ses frères de lait.

Avec ce fragment des classiques, je voudrais faire précéder la traduction de la publication du blog de Roy T. Fielding Les API REST doivent être basées sur l'hypertexte. Un merci spécial à habr.com/users/arthuriantech pour le lien vers le matériel.

Cette semaine sur Habré a été marquée comme la semaine de l'API REST (Full). En ce sens, j'ai toujours été troublé par la présence du préfixe REST dans ce terme. Et, en fin de compte, pas seulement moi. Aujourd'hui, je vais le lire moi-même et inviter tout le monde à savoir ce que Roy T. Fielding en a pensé en 2008. Bien sûr, quelqu'un rampe nerveusement sur un tabouret et dit: dites à Roy, Benya sait pour l'API REST. Néanmoins, nous allons commencer.

Je suis découragé par la pensée du nombre de personnes qui appellent une interface basée sur l'API REST du protocole HTTP. L'exemple d'aujourd'hui est l'API REST SocialSite. Ceci est un RPC. Il s'agit d'un RPC flagrant. Cela démontre des liens si durs qu'il est temps pour lui d'attribuer la catégorie du porno dur.

Que faut-il faire pour qu'ils comprennent que l'hypertexte est un élément nécessaire dans l'architecture REST? En d'autres termes, si le mécanisme d'état de l'application (et donc l'API) n'est pas basé sur l'hypertexte, il ne peut pas être RESTful et ne peut pas être une API REST. Le point. Quel livre dois-je réécrire pour que ce soit clair?

Développeurs d'API, faites attention aux règles suivantes avant d'appeler vos créations d'API REST:

L'API REST ne doit pas dépendre d'un protocole de communication spécifique, bien que sa mise en correspondance réussie avec ce protocole puisse dépendre de la disponibilité des métadonnées, du choix des méthodes, etc. En général, tout protocole dans un schéma d'URI doit permettre à n'importe quel schéma d'URI d'être utilisé pour l'identification. [L'erreur ici est que l'identification n'est pas distincte de l'interaction.]

L'API REST ne doit contenir aucune modification des protocoles de communication, à l'exception du remplissage ou de la correction des détails des bits insuffisamment définis des protocoles standard, tels que la méthode HTTP PATCH ou le champ d'en-tête Link. Les solutions de contournement pour les implémentations non fonctionnelles (telles que les navigateurs suffisamment stupides pour croire que HTML définit un ensemble de méthodes HTTP) doivent être déterminées séparément ou, au moins dans les applications, dans l'espoir que la solution de contournement deviendra finalement obsolète. [L'erreur ici est que les interfaces de ressources sont spécifiques et non universelles.]

L'API REST devrait consacrer presque tous ses efforts descriptifs à la définition des types de médias utilisés pour représenter les ressources et à la gestion de l'état de l'application, ainsi qu'à la définition de relations étendues et de noms de balisage hypertexte pour les types de médias standard existants. Tout effort consacré à décrire les méthodes à utiliser avec quels URI d'intérêt devrait être entièrement défini dans le cadre des règles de traitement pour le type de support (et, dans la plupart des cas, déjà défini par les types de support existants). [L'erreur ici est que les informations externes à la ressource contrôlent l'interaction au lieu de l'hypertexte.]

L'API REST ne doit pas définir de noms de ressources fixes ou d'espaces de noms (connectivité étroite client-serveur). Les serveurs doivent avoir la liberté de gérer leurs propres espaces de noms. Au lieu de cela, laissez les serveurs indiquer aux clients comment créer les URI appropriés, par exemple, dans les formulaires HTML et les modèles d'URI, en définissant ces instructions dans les types de supports et les relations de référence. [L'erreur ici est que la structure de la ressource est définie en dehors de cette ressource, par exemple, dans une norme spécifique au domaine, qui est en fait un analogue de la relation fonctionnelle RPC].

L'API REST ne doit jamais avoir de ressources "typées" importantes pour le client. Les auteurs de spécifications peuvent utiliser des types de ressources pour décrire l'implémentation du serveur derrière l'interface, mais ces types doivent être non pertinents et invisibles pour le client. Les seuls types importants pour le client sont le type de support de la vue actuelle et les noms de relation standardisés. [voir ci-dessus]

L'API REST doit être entrée sans aucune connaissance préalable autre que l'URI initial et un ensemble de types de médias standardisés adaptés au public cible (c'est-à-dire attendu du côté client, qui peut utiliser l'API). A partir de ce moment, toutes les transitions des états d'application doivent être déterminées par le choix des options fournies par le serveur présentes dans les vues reçues, ou par les manipulations de l'utilisateur avec ces vues. Les transitions peuvent être déterminées (ou limitées) par la connaissance du client des types de médias et des mécanismes de communication des ressources qui peuvent être améliorés à la volée (par exemple, le code sur demande). [L'erreur ici est que les informations externes à la ressource contrôlent l'interaction au lieu de l'hypertexte.]

J'ai peut-être manqué quelque chose, mais les règles ci-dessus sont essentielles pour l'hypertexte, qui sont le plus souvent violées dans la soi-disant API REST. Veuillez essayer de les respecter ou choisissez un autre mot à la mode pour votre API.

Cet article de Roy T. Fielding a déclenché une discussion dans les commentaires. Je propose de prendre connaissance de la partie de la discussion, qui était accompagnée des réponses de l'auteur.

Question:

Dans quel sens utilisez-vous ici le terme "hypertexte"? Dois-je lire votre travail pour comprendre ce que vous voulez dire, ou y a-t-il quelque chose en ligne qui révèle la signification de ce concept?

La réponse est:

J'ai une diapositive dans mon exposé REST qui explique ce que signifie hypertexte (et hypermédia).

L'hypertexte a plusieurs définitions:

La définition initiale de Ted Nelson était axée sur les documents non linéaires.

Par «hypertexte», j'entends un document non linéaire - un texte qui bifurque et permet au lecteur de faire un choix, un document facile à lire sur un écran interactif. Il est généralement admis qu'il s'agit d'une séquence de blocs de texte liés par des liens qui offrent au lecteur différents itinéraires. [Theodore H. Nelson]


L'hypertexte est devenu plus tard associé à un mécanisme d'interface utilisateur spécifique.

L'hypertexte est un support de stockage assisté par ordinateur dans lequel les documents associés sont affichés avec leurs liens sur un écran d'ordinateur haute résolution. [Jeffrey Conklin]


Quand je dis "hypertexte", je veux dire la présentation simultanée d'informations et de contrôles de telle sorte que les informations deviennent disponibles, grâce auxquelles l'utilisateur (ou la machine) a le choix et choisit les actions. Hypermédia est simplement une extension de ce que signifie le texte pour inclure des ancres temporaires dans le flux multimédia; la plupart des chercheurs ont rejeté cette distinction.

L'hypertexte n'a pas besoin d'être HTML pour le navigateur. Les machines peuvent suivre des liens lorsqu'elles comprennent le format de données et les types de relations.

Dave Johnson (auteur de l'API critiquée):

J'ai peut-être donné un libellé flou. Je n'ai jamais voulu prétendre que les API RPC OpenSocial ou SocialSite étaient RESTful. Plus d'informations sur mon blog rollerweblogger.org/roller/entry/the_x_rated_socialsite_api .

La réponse est:

Le protocole OpenSocial RESTful n'est pas RESTful. Cela peut être résolu avec des modifications relativement petites, mais maintenant, il ne s'agit que de compresser les résultats RPC dans les types courants de supports Web.

La véritable API RESTful ressemble à un hypertexte. Chaque unité d'information adressable porte une adresse, soit explicitement (par exemple, attributs de lien et id), soit implicitement (par exemple, obtenue à partir de la définition du type de support et de la structure de présentation). Les résultats de la requête sont représentés par une liste de liens contenant des informations récapitulatives, plutôt que par des tableaux de représentations d'objets (la requête ne remplace pas l'identification des ressources). Les représentations de ressources sont auto-documentées: le client n'a pas besoin de savoir si cette ressource est un OpenSocialist, car cela affecte simplement les représentations reçues.

Pensez-y en termes d'Internet. Combien de navigateurs Web connaissent la différence entre une ressource bancaire en ligne et un wiki? Pas l'un d'eux. Ils n'ont pas besoin de connaître les types de ressources. Ce qu'ils ont besoin de savoir, ce sont des transitions d'état potentielles: liens et formes, et quel type de sémantique ou d'action est impliqué lors de la traversée de ces liens. Le navigateur les présente comme des contrôles d'interface utilisateur distincts afin que l'utilisateur puisse voir les transitions potentielles et anticiper l'effet des actions sélectionnées. Les bots peuvent les suivre dans la mesure où l'on sait que les actions sont sûres. Les relations typées, les types de supports spécifiques et les éléments liés à l'action fournissent les conseils nécessaires aux agents automatisés.

Liens utiles:
1. Version de traduction de habr.com/us/users/arthuriantech

2. La même thèse du vieux Roy