Aller au contenu

Logo litteractiv

Lire et comprendre le standard

Cette page a pour objectif de fournir des clés de lecture pour comprendre le standard des événements littéraires du Québec.

Le standard ne décrit pas uniquement des structures de données :
il formalise aussi des intentions d’usage, des niveaux de visibilité et des rôles distincts entre les entités.

Cette documentation explique comment interpréter ces choix afin de :

  • mieux lire la documentation générée ;
  • comprendre les différences entre les entités ;
  • interpréter correctement les options liées aux profils d’API.

Entités primaires et entités secondaires

Le standard distingue deux grandes catégories d’entités : primaires et secondaires.

Entités primaires

Les entités primaires représentent des objets identifiables et autonomes.

Elles :

  • possèdent un identifiant propre ;
  • peuvent exister indépendamment d’un autre objet ;
  • correspondent à des concepts métiers stables.

Exemples d’entités primaires :

Ces entités sont généralement :

  • stockées durablement ;
  • consultables via des endpoints dédiés ;
  • réutilisables dans plusieurs contextes.

Entités secondaires

Les entités secondaires sont des structures de description, utilisées dans le contexte d’un échange ou d’un autre objet.

Elles :

  • n’ont pas vocation à exister seules ;
  • servent à structurer une information précise ;
  • ne sont généralement pas exposées comme ressources autonomes.

Exemples d’entités secondaires :

Une entité secondaire :

  • prend son sens uniquement dans le contexte d’une entité primaire ;
  • n’est pas conçue pour être interrogée isolément ;
  • facilite la lisibilité et la standardisation des échanges.

Profils d’API

Certaines entités du standard définissent des profils d’API.

Les profils d’API indiquent dans quel contexte une donnée peut être exposée, et à qui elle est destinée.

Principe général

Les profils permettent de distinguer :

  • les données destinées à la visibilité publique ;
  • les données destinées à la gestion interne ou aux échanges entre systèmes.

Ils ne définissent pas des permissions techniques, mais des intentions de diffusion.

Profil public

Le profil public correspond aux données :

  • affichables sur un site web ;
  • partageables avec le grand public ;
  • ne contenant pas d’informations sensibles ou administratives.

Il est conçu pour :

  • la visibilité ;
  • la consultation ;
  • la diffusion externe.

Profil privé

Le profil privé correspond aux données :

  • nécessaires à la gestion ;
  • utilisées dans les échanges entre systèmes ;
  • contenant des informations personnelles, contractuelles ou financières.

Il est destiné :

  • aux outils de gestion ;
  • aux plateformes internes ;
  • aux intégrations entre logiciels.

La colonne « API » dans la documentation des entités

Dans la documentation générée des entités, une colonne API précise comment chaque attribut est exposé ou non selon les profils.

Cette colonne décrit une recommandation pour le comportement attendu de l’API, et non une contrainte technique stricte.

Options possibles

Sortie obligatoire / optionnelle

Indique si un champ :

  • doit toujours être présent dans la sortie API ;
  • ou peut être omis selon le contexte.

Format de sortie

Le format précise comment la donnée est exposée :

  • Objet : entité structurée (par une autre entitée) ou donnée simple (texte, nombre, booléen, etc.) ;
  • Liste : collection d’objets ou de valeurs ;
  • Référence : pointeur vers une autre entité via sont identifiant unique.

Ces formats servent de guide pour l’implémentation des API.

Référence inverse

La référence inverse indique qu’un lien existe au niveau du modèle de données, mais qu’il n’est pas destiné à être résolu directement dans l’API.

Elle permet de :

  • documenter les relations entre entités ;
  • rappeler qu’un lien logique existe.

Cependant, dans ce cas elle recommande l'implémentation suivante :

  • l’API ne retourne pas les objets liés ;
  • l'API expose un un endpoint dédié, avec un filtre approprié, pour récupérer ces données.

La référence inverse sert donc à la compréhension du modèle, pas à l’exposition directe des données.

En résumé

Cette page permet de comprendre que :

  • toutes les entités n’ont pas le même rôle ;
  • les profils d’API expriment des intentions de diffusion ;
  • la colonne API guide l’usage attendu des données ;
  • certaines relations sont documentées sans être exposées directement.

Ces conventions garantissent :

  • une lecture cohérente du standard ;
  • une implémentation plus prévisible ;
  • une séparation claire entre visibilité publique et gestion interne.