Gabarits d’URI (RFC 6570) : développer les quatre niveaux

Qu’est-ce qu’un gabarit d’URI ?

Un gabarit d’URI est une URL trouée. Un nom entre accolades au milieu d’un chemin est un trou ; une liste entre accolades en fin d’adresse, commençant par un point d’interrogation, en est un autre, et devient une chaîne de requête. Donnez-lui des valeurs et il devient une vraie URL. Le format est la RFC 6570, et il fait bien plus qu’une substitution de chaînes : il distingue un segment de chemin d’un paramètre de requête, échappe chacun selon ses propres règles, et sait transformer une liste en plusieurs paramètres répétés.

Vous en avez presque certainement reçu sans qu’on vous le dise. Demandez n’importe quoi à l’API de GitHub et la réponse en regorge : le document racine à lui seul renvoie des champs se terminant par un identifiant de gist entre accolades et par un couple de paramètres de pagination lui aussi entre accolades. C’est tout l’intérêt du format : le serveur décrit une fois la forme d’un espace d’URL et le client remplit les trous, au lieu que chaque client concatène des chaînes à la main en se trompant d’échappement.

Il y a quatre niveaux. Le premier, c’est la substitution nue. Le deuxième ajoute les deux expansions qui laissent passer les barres obliques et les autres caractères réservés sans y toucher. Le troisième ajoute les opérateurs de chemin, de requête et de fragment, et permet de nommer plusieurs variables dans une même expression. Le quatrième ajoute les deux modificateurs de valeur : ne garder que les premiers caractères, ou éclater une liste en paramètres répétés. Un vrai gabarit GitHub s’arrête au niveau 3, ce qui mérite d’être su, car le niveau 4 est précisément là où les implémentations commencent à diverger.

Comment l’utiliser

1. Collez un gabarit. Tout ce qui est entre accolades est une expression ; le reste est recopié tel quel, les caractères qu’une URL ne peut pas porter étant encodés au passage. Les boutons d’exemple couvrent un vrai gabarit d’API, un paramètre répété, l’expansion réservée et un préfixe.
2. Donnez-lui des valeurs en JSON. Une chaîne est une valeur simple, un tableau une liste, un objet un ensemble de paires nom-valeur. Omettre un nom n’est pas une erreur : une variable indéfinie ne produit rien, ce qui est exactement le fonctionnement des paramètres facultatifs.
3. Lisez le détail. Sous le résultat, une ligne par morceau du gabarit avec le morceau d’URL qu’il a produit. C’est là que les règles d’échappement deviennent visibles, et là qu’une erreur apparaît sous la forme d’une ligne qui s’est apportée elle-même, inchangée.

Un gabarit défectueux vous donne quand même une URL

Écrivez un gabarit comportant une erreur et cet outil ne s’arrêtera pas. Il développera tout ce qu’il peut, recopiera la partie fautive exactement telle que vous l’avez écrite, et vous dira en dessous ce qui ne va pas. Ce n’est pas de l’indulgence, c’est la spécification : lorsqu’un processeur rencontre une expression incorrecte, la partie non traitée doit être recopiée dans le résultat sans être développée, le traitement doit se poursuivre, et l’appelant doit être informé de l’emplacement et du type de l’erreur. La RFC qualifie le résultat de sortie destinée au seul diagnostic.

Qu’un format d’hypermédia soit écrit ainsi a une raison. Les gabarits que vous développez viennent souvent d’ailleurs, dans la réponse d’une API que vous n’avez pas écrite, et un client qui explose devant un champ inattendu vaut moins qu’un client qui continue en signalant le problème. Les deux modes de défaillance sont d’ailleurs délibérément différents : un caractère interdit hors d’une expression arrête net l’analyse, si bien que tout ce qui suit — y compris des expressions qui auraient fonctionné — reste exactement tel quel. Essayez l’exemple fautif et regardez quelles parties se développent encore.

Le hic, c’est que presque personne n’implémente la partie signalement. Deux processeurs publiés ont été mesurés pendant la construction de cette page : face aux trente-six gabarits que la suite de tests du format elle-même déclare invalides, aucun n’a levé d’exception et aucun n’a renvoyé la moindre indication d’erreur. Tous deux ont rendu à chaque fois une URL d’apparence plausible, et sur cinq des trente-six ils ont rendu des URL différentes l’un de l’autre. Si vous vous êtes déjà demandé pourquoi un gabarit malformé a produit une requête erronée plutôt qu’une pile d’appels, voilà pourquoi.

Une spécification sans interdictions

La RFC 6570 ne contient aucun MUST NOT ni aucun SHOULD NOT — pas un seul, hors du paragraphe d’usage qui explique le sens de ces mots. Dans tout le document, on trouve quatre MUST, sept SHOULD et trois MAY. C’est inhabituel, et cela explique le reste : quand le traitement des erreurs est rédigé au SHOULD, une implémentation est conforme qu’elle le suive ou non, et en général elle ne le suit pas.

Il y a aussi un endroit où elle se contredit, et l’outil suit ici la suite de tests plutôt que la grammaire. La règle sur ce qui peut figurer hors d’une expression exclut l’apostrophe et la cite nommément parmi les caractères interdits. Or une apostrophe est licite dans une URL, la section juste au-dessus dit que les caractères licites dans une URL sont recopiés tels quels, et la suite officielle de conformité contient un cas exigeant que l’apostrophe survive — classé sous le numéro de la section même dont la grammaire l’interdit. Ici, la suite l’emporte.

Une dernière règle qui mérite d’être connue parce qu’elle ne se voit pas dans le gabarit. Demander les premiers caractères d’une valeur compte des caractères, pas les unités dans lesquelles un langage de programmation les range. La spécification le dit deux fois et en donne la raison : il s’agit d’empêcher une implémentation de couper un caractère en deux. Demandez aux deux bibliothèques mesurées le premier caractère d’une clé de sol et aucune ne le rend : toutes deux lèvent une erreur, car couper une chaîne JavaScript à la position un scinde ce caractère en deux moitiés et laisse un fragment invalide.

Ce que cet outil ne fait pas

Il ne fonctionne pas dans l’autre sens. Extraire les valeurs d’une URL déjà formée — apparier plutôt que développer — est un problème nettement plus difficile, et la RFC s’en défausse elle aussi, dans ses propres termes : l’appariement, dit-elle, ne marche bien que si les expressions sont délimitées par les extrémités de l’URL ou par des caractères qui ne peuvent pas figurer dans l’expansion, et de façon générale les expressions régulières se prêtent mieux à cette tâche. Un gabarit qui se termine par deux variables collées, sans rien entre elles, n’a pas de réponse unique.

Il ne va rien chercher et ne vérifie pas que l’URL produite existe. Un gabarit qui se développe en une adresse parfaitement formée d’une ressource que personne n’a jamais créée ressemble exactement à un gabarit qui marche. À retenir aussi dans l’autre sens, avec les mots de la spécification : un gabarit n’est pas un URI. Il n’identifie aucune ressource, il n’est pas analysé comme tel, et il ne devrait pas être placé là où l’on attend un URI tant que quelque chose ne l’a pas développé — c’est précisément pourquoi une API qui sert des gabarits leur donne des noms de champ à part plutôt que de les mêler aux liens achevés.

Les résultats affichés ici sont contrôlés contre la suite de conformité de la spécification elle-même, et non contre une autre bibliothèque : les 117 cas positifs, et les 36 gabarits invalides signalés comme tels au lieu d’être développés en silence. S’accorder avec une autre implémentation montrerait seulement que deux personnes ont fait les mêmes choix.

Pourquoi est-ce gratuit ?

Développer un gabarit relève du traitement de chaînes, et cela se passe dans votre navigateur. Aucun serveur n’intervient, il n’y a donc rien à facturer ni de compte à créer.

Rien n’est envoyé. Le gabarit que vous collez et les valeurs que vous saisissez restent dans cet onglet.