L’en-tête Link porte des relations au sujet de la réponse qui le transporte. Deux spécifications étendent cela à des liens au sujet d’autre chose, dans un document à part, et Symfony parle désormais les deux.
Le point de départ est la RFC 8288, qui définit le liage web et le champ d’en-tête Link. Elle a rendu obsolète la RFC 5988 en 2017, détail qui mérite d’être mentionné parce que le composant WebLink de Symfony pointait encore l’ancien numéro il y a peu.
Les jeux de liens : des liens au sujet d’une ressource que vous n’envoyez pas
La RFC 9264 définit un document qui porte un jeu de liens hors de toute interaction HTTP. Deux formats : application/linkset, qui est la valeur du champ d’en-tête avec les sauts de ligne autorisés, et application/linkset+json.
Ce que cela apporte est le cas que l’en-tête ne sait pas servir. Une réponse ne peut porter que des liens à son propre sujet, et l’en-tête a un budget de taille partagé avec tout le reste. Un jeu de liens est une ressource : il peut décrire une autre ressource, être mis en cache selon ses propres règles, être volumineux, et être publié à une adresse bien connue que les clients découvrent une fois.
{
"linkset": [
{
"anchor": "https://api.example.com/books/42",
"author": [ { "href": "https://api.example.com/authors/7" } ],
"license": [ { "href": "https://creativecommons.org/licenses/by/4.0/" } ]
}
]
}
L’anchor en est tout l’intérêt : chaque entrée dit de quoi elle parle, si bien qu’un seul document décrit de nombreuses ressources.
Link-Template : un lien avec des trous dedans
La RFC 9652 ajoute le champ d’en-tête Link-Template, dont la cible est un gabarit d’URI plutôt qu’un URI. C’est le client qui remplit les variables.
Link-Template: "/books/{id}{?fields}"; rel="item"; var-base="https://api.example.com/vars/"
C’est ainsi qu’une API annonce une forme plutôt qu’une énumération. Une collection de dix mille livres ne peut pas lister ses éléments dans un en-tête ; elle peut dire comment en adresser un. var-base dit ensuite où vivent les descriptions de ces variables, de sorte qu’un client peut apprendre ce que fields accepte.
Notez les guillemets autour du gabarit. Un en-tête Link enveloppe sa cible dans des chevrons ; un Link-Template l’enveloppe dans des guillemets doubles, parce qu’un gabarit porte des accolades et d’autres caractères que la forme à chevrons ne peut pas contenir sans ambiguïté. En lisant les deux côte à côte, c’est cette différence qui fait trébucher un analyseur écrit à la main.
Il y a dans Symfony une conséquence pratique bonne à connaître : jusqu’ici, un lien à gabarit remis à l’écouteur était écarté en silence, l’en-tête Link n’ayant nulle part où le mettre. Il sort maintenant dans son propre en-tête.
Ce dont l’implémentation avait réellement besoin
L’agréable surprise, et un bon signe sur la conception du composant : application/linkset n’a demandé aucun code. C’est la valeur du champ d’en-tête avec les sauts de ligne pour séparateurs, ce que l’analyseur existant accepte déjà et que le sérialiseur existant produit déjà.
Le format JSON a demandé un sérialiseur et un analyseur, le champ d’en-tête a demandé un nouveau chemin dans l’écouteur, et le reste tenait en quatre références de documentation pointant le bon numéro de RFC. La pull request est petite au regard de ce qu’elle ajoute, ce qui veut en général dire que l’abstraction en dessous était juste.
Où cela compte
Dans la découverte d’API, surtout. Un client qui trouve un jeu de liens sait où sont la documentation, la licence, les formats alternatifs et les ressources liées, sans convention convenue par courriel. C’est la moitié lisible par une machine de ce que la page d’accueil d’une API fait pour un humain.
Et cela se compose avec ce que le composant faisait déjà : les indications de préchargement, la prélecture, et les relations qu’une réponse porte à son propre sujet. Même vocabulaire, trois endroits où le poser.