API du module de recherche de Combo¶

• recherche dans les demandes
• recherche dans les utilisateurs
• recherche dans les pages du portail
• recherche de code de suivi

Le module de recherche peut être étendu à d'autres systèmes dès qu'ils proposent un webservice compatible. Ce document détaille le format du webservice attendu.

Requête¶

Le système de recherche de Combo va lancer une requête HTTP GET sur une URL, en lui envoyant en paramètre (query-string) la chaîne de caractère saisie par l'utilisateur :

GET https://example.net/search/?q=foobar

Le nom du paramètre "q" est en fait libre, dans les exemples qui suivent nous continuerons à l'appeler "q". "foobar" est la chaîne de caractère saisie par l'utilisateur.

Combo peut également envoyer un paramètre contenant l'email de l'utilisateur effectuant la recherche. Cela permet au système tiers de ne renvoyer que les résultats pertinents pour cet utilisateur. Exemple de requête :

GET https://example.net/search/?email=login@example.org&q=foobar

Ici encore le paramètre "email" peut être nommé autrement.

Dans des intégrations plus fortes, si le système tiers est déjà lié à Publik par un SSO, il est possible d'envoyer dans la requête l'identifiant de fédération (sub ou NameID).

Réponse¶

La requête GET doit recevoir une réponse en JSON, sous la forme suivante :

GET https://example.net/search/?q=foobar

200 OK
Content-type: application/json

{
  "err": 0,
  "data": [
    {
      "url": "https://files.example.net/dossier/3/",
      "text": "Dossier foobar",
      "description": "Dossier numéro <b>3</b>, en date du <i>10/12/2019</i>" 
    },
    { ...objet2... }, ...
  ]
}

• err est un entier, 0 indique que tout s'est bien passé. Toute autre valeur est interprétée comme une erreur
• data est une liste des objets trouvés, dans l'ordre de pertinence
• chaque objet est un dictionnaire contenant les clés/valeurs suivantes
  • text : nom de l'objet, sur une seule ligne, qui sera affiché à l'utilisateur effectuant la recherche
  • url : l'URL de l'objet, typiquement un lien vers la page du système tiers qui va afficher l'objet
  • description (optionnel) : une description plus longue, autorisant un peu de formatage HTML si besoin

Personnalisation de l'affichage des résultats¶

Un objet peut contenir d'autres clés dont les valeurs sont jugées utiles à présenter à la personne qui fait une recherche. Par exemple sur une recherche d'usager, on pourrait avoir :

  "data": [
    {
      "url": "https://users.example.net/user/3/",
      "text": "Ferdinand Poitevin",
      "first_name": "Ferdinand",
      "last_name": "Poitevin",
      "dob": "1860-10-09",
      "phone": "+33123456789",
      "mobile": "+33612345678",
      "address": "169 rue du Château, Paris" 
    }, ...

Ces valeurs peuvent être utilisées pour personnaliser le rendu des résultats. Un gabarit sera programmé dans Combo pour afficher le résultat du moteur.

Personnalisation en fonction de l'usager¶

Combo peut envoyer un paramètre « email=... » lors de la recherche. Dans ce cas, les résultats peuvent être modulés en fonction de cet email, qui représente utilisateur qui effectue la recherche.

• de ne pas remonter certains objets résultats qui ne doivent pas être affichés à l'utilisateur
• de ne pas donner certains détails sur certains résultats
• de ne pas indiquer d'URL si l'objet n'est en fait pas accessible à l'utilisateur (on lui affichera juste que l'objet existe)
• de changer l'ordre de pertinence
• etc.

Exemple de rendu¶