API REST – Support de la clé fonctionnelle

Support
1

Bonjour,

Dans le cadre de l’exposition de nos objets métier via les API REST Simplicité, nous sommes aujourd’hui limités à l’utilisation du row_id comme identifiant technique dans les endpoints.

Or, pour certains objets métier, nous disposons d’une clé fonctionnelle stable, connue des systèmes consommateurs et déjà utilisée comme clé d’unicité métier.

Dans notre cas concret, nous avons l’objet LbcLegalText, dont la clé fonctionnelle est portée par l’attribut LegalTextId.

:backhand_index_pointing_right: Besoin fonctionnel

Permettre aux consommateurs de l’API de retrouver, lire, mettre à jour ou supprimer une ressource directement à partir de sa clé fonctionnelle, sans avoir à effectuer au préalable une recherche pour récupérer le row_id.

Cela permettrait d’exposer des endpoints plus lisibles et plus alignés avec le modèle métier, par exemple : functionalkey =legalTextId

GET /legalTexts/{functionalkey}

en + de :

GET /legalTexts/{row_id}

:backhand_index_pointing_right: Question ouverte sur les possibilités Simplicité (choix d’implémentation)

Nous avons identifié deux approches possibles côté framework, et souhaiterions avoir votre avis sur celle à privilégier, ou sur l’existence d’un mécanisme natif équivalent.

:one: Approche “path param étendu”

  • Autoriser un endpoint du type :
GET /legalTexts/{functionalKey}
  • Avec une résolution interne du functionalKey vers le row_id (via recherche sur la clé fonctionnelle).
  • Le format pourrait être reconnu implicitement ou via une configuration spécifique au niveau de l’objet.Cette solution est dégradé (en réflexion, dans l’hypothèse qu’on saura patcher la requete).

:two: Approche via URI_MAPPING / routage personnalisé

  • Déclarer un mapping spécifique reconnaissant un format de path dédié
    (ex : /legalTexts/by-functional-key/{key})
  • Déclencher automatiquement un search ou un select basé sur la clé fonctionnelle.

:backhand_index_pointing_right: Points de réflexion complémentaires

  • Objets avec plusieurs clés fonctionnelles :
    Existe-t-il une recommandation pour gérer ce cas de manière standard (mapping explicite, configuration par objet, priorité d’une clé) ?

  • Tables d’association exposées en API :
    pour les objets d’association, le row_id n’a généralement pas de sens métier et les clés sont souvent composites.
    Dans notre cas, nous avons les objets LegalText et Content, liés via la table d’association lbcLegalTextContent, exposée en API.
    Fonctionnellement, l’unicité d’un contenu n’est pas portée par un contentId technique (équivalent au row_id), mais par le LegalTextId associé et la langue du contenu.

Dans ce contexte, nous souhaiterions exposer l’association via une clé fonctionnelle composite dans l’API (par exemple) : {functionalkey} = {legalTextId} - {contentLanguage}

GET /legalContent/{functionalkey}

Existe-t-il des bonnes pratiques ou mécanismes recommandés dans Simplicité pour exposer ce type de ressource d’association par clé fonctionnelle, ou via des sous-ressources REST ?

L’objectif n’est pas de remplacer le row_id, mais de d’ajouter un accès REST plus métier et optionnel, tout en restant compatible avec les standards Simplicité et les évolutions futures.

Merci d’avance pour votre retour et vos recommandations.

Cordialement,

3

Bonjour

Juste pour préciser le contexte de cette demande, on parle ici bien uniquement des APIs “mappées” (RESTMappedObjectsExternalObject) ?

4

Hello David, Oui exactement :slight_smile:

5

OK on va regarder s’il est possible de pouvoir désigner une combinaison ordonnée d’attributs comme “clé métier unique”.

Dans l’idée on parlerait bien des attributs de la clé fonctionnelle mais ça pourrait être potentiellement plus spécifique et, en outre, il y a de nombreuses subtilités à avoir en tête (qu’il n’y a pas avec un row ID technique):

  • ll faut tenir compte du fait que, par exemple, l’ordre de ces attributs peut être changé au niveau du paramétrage l’objet (ex: pour des besoins UI) mais il ne faut pas que ça impacte l’API mappée => le mapping doit donc impérativement définir l’ordre dans lequel ces attributs doivent être parsés dans l’URL
  • Un séparateur - n’est clairement pas le bon choix pour séparer les valeurs d’attributs d’une clé unique multi attributs (car - peut être classiquement présent dans les valeurs, par exemple dans les dates techniques YYYY-mm-dd), il faut donc idéalement aussi être capable de configurer le séparateur ad hoc (en utilisant par défaut un séparateur plus “atypique” et URL-fiendly genre ~)
  • Sur certains types d’attributs il faut voir quelle valeur utiliser entre la valeur technique et la valeur traduite (ex: liste de valeur, date, …), je préconise de n’utiliser que les valeurs techniques (de toute façon une date avec des / ne serait pas une bonne idée)
  • Il va y avoir de la redondance des clefs fonctionnelles sur plusieurs niveaux (ex: dans le cas de la démo, la référence produit est unique par fournisseur dans une approche générique on aurait donc pas une URL suppliers/BIM/products/REF001 mais suppliers/BIM/products/BIM~REF001)
  • Quid des espaces dans les valeurs ? car non URL-friendly
  • Etc.

Bref, dans le cas général, une simple concaténation d’attributs clé fonctionnelles n’est pas URL-friendly ni forcément toujours très user-friendly…

NB: nous allons creuser cette demande dans le cadre de la version de dev actuelle = v7. Ensuite, si ça aboutit à quelque chose de faisable et de fiable et si ça peut être backporté en v6, ça ne le sera que sur la v6 actuelle = la 6.3 (la 6.2 est désormais en fin de vie, on n’y backportera plus aucune évolution). Bref prévoyez de passer en 6.3 rapidement

7

A la réflexion il semble plus cohérent de se s’appuyer de la notion existante de “permalinks” (introduite en v6). Pour rappel ce mécanisme sert pour gérer des liens directs vers les formulaires de la UI mais sa généralisation à la couche d’API pourrait être une bonne chose.

On va livrer dans le cadre de la 6.3.2 un 1er jet de ce que ça pourrait donner en se focalisant à ce stade uniquement sur les APIs mappées

Dans ce 1er jet on est soumis à une contrainte de nommage forte = il faut impérativement configurer le permalink de l’objet au format /<nom mappé de l'objet>-[USERKEY] (ce qui exclue mécaniquement des mappings sur plusieurs noms).

Par exemple sur la démo avec l’objet DemoSupplier, qui est mappé sur une API mappée en tant que suppliers, si on configure ce permalink:

image
image2432×1176 141 KB

On a alors la possibilité d’accéder au record du supplier “BIM” via l’API mappée sur la clé [USERKEY] à savoir ici bim ou BIM(les permalinks sont case-insensitive)
image
image900×757 40.4 KB

A noter que la conversion générique des valeurs d’attributs en snake case utilisée par les permalinks a un effet sur certaines valeurs, ex: le [USERKEY] du produit “REF006” du fournisseur “LLED” donne lled-ref-006 (à noter le - ajouté entre refet 006).

Si ça va dans le bon sens on verra pour faire évoluer ça vers plus de souplesse.