[Partiel] Ajout d'une API REST métier pour obtenir les réponses aux questions "smiley" des avis d'une (liste de) démarche(s)

[lucaa]

Paramètres d'entrée:

• identifiant d'une démarche, ou liste d'identifiants des démarches
• date de début de la période - date calendrier sans heure dans la journée
• date de fin de la période - date calendrier sans heure dans la journée
• question
  • dans cette première version on prévoit de fournir uniquement les réponses aux questions à réponse 'smiley': satisfaction globale ("comment s'est passé cette démarche pour vous"), facilité ("était-ce facile à utiliser"), compréhensibilité ("Le langage employé était-il facile à comprendre")

Sortie:

• [uniquement si plusieurs démarches sont demandées] liste des démarche identifiées par leur ID avec, pour chaque démarche:
  • le nombre de réponses de chaque type (pasbien / non, moyen, tres bien / oui) pour la question spécifiée, enregistrés dans la période spécifiée en entrée
• le niveau de granularité de cette API est la journée - autrement dit, les dates de début et de fin sont interprétées comme des jours entiers (qui commencent à 00:00:00 inclusif et finissent à 23:59:59 inclusif), il n'est pas possible de spécifier une période qui commence à une heure plus tard dans la journée
• si la date de début n'est pas spécifiée, les réponses depuis le début du projet sont fournies
• si la date de fin n'est pas spécifiée, les réponses jusqu'au moment de la question sont fournies, dans les limites de mises à jour des caches des données agrégées (voir Agrégation des données des avis pour remplacer tous les usages qui calculent aujourd'hui ces données à partir des avis détaillés #1129 ).

Règles générales pour l'API:

• authentification - les mêmes que fournies dans les APIs REST de la plateforme XWiki utilisée
• le language à utiliser pour les paramètres et clés dans les réponses est l'anglais

[ClementNumericite]

@lucaa c'est ici que je peux suivre les avancées coté API REST ?

[lucaa]

@ClementNumericite oui, c'est ce ticket.

[lucaa]

L'API pour accéder aux statistiques d'avis d'une seule démarche est ajoutée, accessible par l'endpoint REST de la plateforme XWiki, documentée ici https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI.

• Authentification: telle que décrite ici https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HAuthentication
  • dans cette première implémentation uniquement les utilisateurs ayant les droits d'administration peuvent accéder aux données par cette API (les porteurs ou administrateurs ministériels n'ont pas accès aux résultats par cette API)
• endpoint: /rest/observatoire/avistats/aggregatebyday/demarche/<numéro de la démarche>?media=json , avec les paramètres suivants, dans l'URL:
  • question - valeurs possibles: easy, satisfaction, comprehensible
    • plusieurs valeurs peuvent être demandées dans la même requête, en répétant plusieurs fois le paramètre avec toutes les valeurs souhaitées
    • ce paramètre est optionnel; en cas d'absence la valeur utilisée est satisfaction .
  • date_end , date de la fin de la période pour les avis, en millisecondes (e.g. 1648763000000) - optionnel
  • date_start date du début de la période pour les avis, en millisecondes (e.g. 1633039200000) - optionnel

La réponse fournira le total des réponses, les dates de la période couverte et un bloc pour chaque question demandée avec les comptages des réponses négatives, neutres et positives:

{"answersTotal":123,
 "comprehensible": 
    {"negative":20,
      "neutral":20,
      "positive":20},
    "dateStart":1529013600000,
    "dateEnd":1678224509694}

Cette API sera activée en production demain matin, suite au redémarrage de maintenance journalier.

[lucaa]

Reste à faire encore:

• Implémentation de la vérification des droits complète pour donner accès aux statistiques de réponses (impl. à base du schéma de droits de la plateforme)
• Amélioration de la réponse fournie lors de la demande des stats pour une démarche inexistante
• API pour obtenir les statistiques pour une liste de démarches

[lucaa]

l'API pour les stats d'une seule démarche est désormais disponible en production.

[lucaa]

Reste à faire encore:

• Implémentation de la vérification des droits complète pour donner accès aux statistiques de réponses (impl. à base du schéma de droits de la plateforme)
• Amélioration de la réponse fournie lors de la demande des stats pour une démarche inexistante
• API pour obtenir les statistiques pour une liste de démarches

Ces 3 elements ont été déplacés vers des nouveaux tickets dédiés: #1208, #1209 et #1210.

Je ferme ce ticket maintenant, la finalisation sera couverte par les 3 tickets nouveaux.