PSR 13 - Hypermedia Links

Les liens hypermédias deviennent une partie de plus en plus importante du Web, à la fois dans les contextes HTML et dans divers contextes de format API. Cependant, il n'y a pas de format hypermédia commun unique, ni de manière commune de représenter les liens entre les formats.

Cette spécification vise à fournir aux développeurs PHP une manière simple et courante de représenter un lien hypermédia indépendamment du format de sérialisation utilisé. Cela permet à son tour à un système de sérialiser une réponse avec des liens hypermédias dans un ou plusieurs formats de fil indépendamment du processus de décision de ces liens.

Les liens de base

Un Lien Hypermédia se compose, au minimum :

• Un URI représentant la ressource cible référencée.
• Une relation définissant la relation entre la ressource cible et la source. Divers autres attributs du lien peuvent exister, selon le format utilisé. Comme les attributs supplémentaires ne sont pas bien standardisés ou universels, cette spécification ne cherche pas à les standardiser. Aux fins de la présente spécification, les définitions suivantes s'appliquent.
• Objet d'implémentation - Un objet qui implémente l'une des interfaces définies par cette spécification.
• Sérialiseur - Une bibliothèque ou un autre système qui prend un ou plusieurs objets Link et en produit une représentation sérialisée dans un format défini.

Les attributs

Tous les liens peuvent inclure zéro ou plusieurs attributs supplémentaires au-delà de l'URI et de la relation. Il n'y a pas de registre formel des valeurs autorisées ici, et la validité des valeurs dépend du contexte et souvent d'un format de sérialisation particulier. Les valeurs couramment prises en charge incluent 'hreflang', 'title' et 'type'. Les sérialiseurs peuvent omettre des attributs sur un objet lien si cela est requis par le format de sérialisation. Cependant, les sérialiseurs devraient coder tous les attributs fournis possibles afin de permettre l'extension d'utilisateur à moins que cela ne soit empêché par la définition d'un format de sérialisation. Certains attributs (généralement “hreflang”) peuvent apparaître plusieurs fois dans leur contexte. Par conséquent, une valeur d'attribut PEUT être un tableau de valeurs plutôt qu'une simple valeur. Les sérialiseurs peuvent coder ce tableau dans le format approprié au format sérialisé (comme une liste séparée par des espaces, une liste séparée par des virgules, etc.). Si un attribut donné n'est pas autorisé à avoir plusieurs valeurs dans un contexte particulier, les sérialiseurs doivent utiliser la première valeur fournie et ignorer toutes les valeurs suivantes. Si une valeur d'attribut est boolean “true”, les sérialiseurs peuvent utiliser des formes abrégées si cela est approprié et pris en charge par un format de sérialisation. Par exemple, HTML permet aux attributs de n'avoir aucune valeur lorsque la présence de l'attribut a une signification booléenne. Cette règle s'applique si et seulement si l'attribut est boolean “true”, pas pour toute autre valeur "véridique" en PHP telle que l'entier 1. Si une valeur d'attribut est boolean “false”, les sérialiseurs devraient omettre entièrement l'attribut à moins que cela ne change la signification sémantique du résultat. Cette règle s'applique si et seulement si l'attribut est boolean “false”, pas pour toute autre valeur "false" en PHP telle que l'entier 0.

Les relations