Skip to content
Snippets Groups Projects
GUILLORET SIMON's avatar
GUILLORET SIMON authored
Merge branch 'feature/91-update-documentation' into 'develop'
aa29320d

Documentation API : Créer un Quiz

Endpoint

POST /quiz/create

Description

Cet endpoint permet de créer un nouveau quiz et retourne ses détails, y compris les questions, les réponses et les métadonnées associées.

Corps de la requête

Champ Type Requis Description
amount number Oui Nombre de questions dans le quiz.
category number Oui ID de la catégorie des questions.
difficulty string Oui Niveau de difficulté (easy, medium, hard).

Exemple de requête

{
  "amount": 5,
  "category": 22,
  "difficulty": "easy"
}

Corps de la réponse

Champ Type Description
id number Identifiant unique du quiz.
codeQuiz string Code unique identifiant le quiz.
score number Score actuel du quiz.
questionIndex number Index de la question actuelle (commence à 1).
questionCount number Nombre total de questions dans le quiz.
theme objet Thème associé au quiz.
- id number Identifiant unique du thème.
- name string Nom du thème.
difficulty objet Niveau de difficulté du quiz.
- id number Identifiant unique du niveau de difficulté.
- name string Nom du niveau de difficulté.
questions tableau d'objets Liste des questions du quiz.
- id number Identifiant unique de la question.
- text string Texte de la question.
- type string Type de la question (multiple, boolean).
- order number Ordre de la question dans le quiz.
- theme objet Thème de la question.
--- id number Identifiant unique du thème.
--- name string Nom du thème.
- answers tableau d'objets Liste des réponses possibles pour la question.
--- id number Identifiant unique de la réponse.
--- text string Texte de la réponse.

Exemple de réponse

{
  "id": 1,
  "codeQuiz": "1IRCXV",
  "score": 0,
  "questionIndex": 1,
  "questionCount": 5,
  "theme": {
    "id": 1,
    "name": "Geography"
  },
  "difficulty": {
    "id": 1,
    "name": "easy"
  },
  "questions": [
    {
      "id": 5,
      "text": "Quelle est la langue officielle du Costa Rica ?",
      "type": "multiple",
      "order": 1,
      "theme": {
        "id": 1,
        "name": "Geography"
      },
      "answers": [
        {
          "id": 13,
          "text": "Espagnol"
        },
        {
          "id": 14,
          "text": "Anglais"
        },
        {
          "id": 15,
          "text": "Portugais"
        },
        {
          "id": 16,
          "text": "Créole"
        }
      ]
    },
    {
      "id": 4,
      "text": "Toronto est la capitale du Canada.",
      "type": "boolean",
      "order": 2,
      "theme": {
        "id": 1,
        "name": "Geography"
      },
      "answers": [
        {
          "id": 11,
          "text": "Faux"
        },
        {
          "id": 12,
          "text": "Vrai"
        }
      ]
    }
  ]
}

Notes

  • Assurez-vous que les valeurs de category et difficulty correspondent aux valeurs valides fournies par l'API. Les entrées invalides renverront une erreur.
  • Le champ order dans le tableau questions indique l'ordre des questions dans le quiz.

Voici la documentation pour la route POST /quiz/answer :


Documentation API : Répondre à une Question

Endpoint

POST /quiz/answer

Description

Cet endpoint permet de vérifier si une réponse donnée est correcte, de mettre à jour le score du quiz, d'incrémenter l'index de la question actuelle, et de retourner les réponses à la question ainsi que le score actuel.


Corps de la requête

Champ Type Requis Description
codeQuiz string Oui Code unique identifiant le quiz.
questionID number Oui Identifiant unique de la question.
answerID number Oui Identifiant unique de la réponse.

Exemple de requête

{
  "id": "1IRCXV",
  "questionID": 4,
  "answerID": 12
}

Corps de la réponse

Champ Type Description
score number Score actuel du quiz après mise à jour.
answers tableau d'objets Liste des réponses associées à la question.
- id number Identifiant unique de la réponse.
- text string Texte de la réponse.
- isCorrect boolean Indique si la réponse est correcte ou non.
- questionId number Identifiant de la question associée.

Exemple de réponse

{
  "score": 3,
  "answers": [
    {
      "id": 11,
      "text": "False",
      "isCorrect": false,
      "questionId": 4
    },
    {
      "id": 12,
      "text": "True",
      "isCorrect": true,
      "questionId": 4
    }
  ]
}

Fonctionnement

  1. Vérifie si la réponse donnée (via answerID) est correcte en se basant sur la question (questionID) et le quiz (codeQuiz).
  2. Si la réponse est correcte, incrémente le score du quiz.
  3. Incrémente l'index de la question actuelle dans le quiz.
  4. Récupère les réponses à la question spécifiée.
  5. Retourne un objet contenant le score actuel et les réponses à la question.

Notes

  • Le champ isCorrect dans les réponses permet d’identifier quelle réponse est correcte.
  • Si la réponse donnée est incorrecte, seul l'index de la question est incrémenté, le score reste inchangé.
  • Le code unique codeQuiz doit correspondre à un quiz existant.

Documentation API : Questions restantes pour un quiz

Endpoint

POST /quiz/remaining

Description

Cet endpoint renvoie les questions restantes d’un quiz en fonction de l’index actuel de la question (questionIndex). Les questions précédentes ne sont pas incluses, et les réponses ne contiennent pas le champ isCorrect.


Corps de la requête

Champ Type Requis Description
codeQuiz string Oui Code unique identifiant le quiz.

Exemple de requête

{
  "codeQuiz": "1IRCXV"
}

Corps de la réponse

Champ Type Description
id number Identifiant unique du quiz.
codeQuiz string Code unique du quiz.
score number Score actuel du quiz.
questionIndex number Index actuel de la question dans le quiz.
questionCount number Nombre total de questions dans le quiz.
theme objet Thème du quiz.
- id number Identifiant du thème.
- name string Nom du thème.
difficulty objet Niveau de difficulté du quiz.
- id number Identifiant du niveau de difficulté.
- name string Nom du niveau de difficulté.
questions tableau d'objets Liste des questions restantes dans le quiz.
- id number Identifiant unique de la question.
- text string Texte de la question.
- type string Type de la question (multiple ou boolean).
- order number Ordre de la question dans le quiz.
- theme objet Thème associé à la question.
-- id number Identifiant du thème.
-- name string Nom du thème.
- answers tableau d'objets Liste des réponses disponibles.
-- id number Identifiant unique de la réponse.
-- text string Texte de la réponse.

Exemple de réponse

{
  "id": 1,
  "codeQuiz": "1IRCXV",
  "score": 2,
  "questionIndex": 2,
  "questionCount": 5,
  "theme": {
    "id": 1,
    "name": "Geography"
  },
  "difficulty": {
    "id": 1,
    "name": "easy"
  },
  "questions": [
    {
      "id": 4,
      "text": "Toronto is the capital city of the North American country of Canada.",
      "type": "boolean",
      "order": 2,
      "theme": {
        "id": 1,
        "name": "Geography"
      },
      "answers": [
        {
          "id": 11,
          "text": "False"
        },
        {
          "id": 12,
          "text": "True"
        }
      ]
    },
    {
      "id": 3,
      "text": "Which of the following languages does NOT use the Latin alphabet?",
      "type": "multiple",
      "order": 3,
      "theme": {
        "id": 1,
        "name": "Geography"
      },
      "answers": [
        {
          "id": 7,
          "text": "Georgian"
        },
        {
          "id": 8,
          "text": "Turkish"
        },
        {
          "id": 9,
          "text": "Swahili"
        },
        {
          "id": 10,
          "text": "Vietnamese"
        }
      ]
    }
  ]
}

Fonctionnement

  1. Vérification du quiz : Récupère le quiz correspondant au codeQuiz.
  2. Filtrage des questions : Sélectionne les questions restantes en fonction de questionIndex.
  3. Exclusion de la propriété isCorrect : Toutes les réponses associées à une question sont renvoyées sans le champ isCorrect.
  4. Retourne le quiz modifié : Inclut les questions restantes avec leurs réponses simplifiées.

Notes

  • La route est conçue pour s'assurer que seules les questions restantes à jouer sont retournées, évitant de révéler des informations inutiles ou les questions déjà jouées.
  • Utile pour reprendre un quiz à un état sauvegardé.

Documentation API : Créer un Quiz Communautaire

Endpoint

POST /quiz/community

Description

Cet endpoint permet de créer un quiz communautaire. Le quiz est stocké dans la base de données mais ne renvoie aucune réponse.


Pré-requis

  • Authentification requise : L'utilisateur doit être connecté et fournir un token d'accès valide dans l'en-tête access_token.

En-têtes de la requête

Champ Type Requis Description
access_token string Oui Jeton d'accès au format Bearer <token>.

Corps de la requête

Champ Type Requis Description
name string Oui Nom du quiz communautaire.
description string Oui Description du quiz communautaire.
difficulty string Oui Niveau de difficulté du quiz (easy, medium, hard).
questions tableau d'objets Oui Liste des questions du quiz.
- text string Oui Texte de la question.
- isMultipleChoice boolean Oui Indique si la question est à choix multiple.
- answers tableau d'objets Oui Liste des réponses associées à la question.
--- text string Oui Texte de la réponse.
--- isCorrect boolean Non Indique si la réponse est correcte. Par défaut, false si non fourni.

Exemple de requête

{
  "name": "My Community Quiz",
  "description": "A quiz created by the community",
  "difficulty": "easy",
  "questions": [
    {
      "text": "What is 2+2?",
      "isMultipleChoice": true,
      "answers": [
        { "text": "4", "isCorrect": true },
        { "text": "3" },
        { "text": "5" },
        { "text": "6" }
      ]
    }
  ]
}

Exemple de réponse

{
  "id": "4M8M0V"
}

Fonctionnement

  1. Vérifie si l'utilisateur est authentifié en utilisant le token fourni dans l'en-tête access_token.
  2. Valide les données envoyées dans le corps de la requête.
  3. Stocke le quiz communautaire dans la base de données.
  4. Ne retourne aucune donnée dans la réponse.

Notes

  • Les réponses correctes doivent être indiquées en définissant isCorrect à true sinon elles sont considérés comme fausses.
  • Les utilisateurs doivent être connectés pour créer un quiz communautaire.
  • Aucune donnée n'est renvoyée après la création du quiz pour éviter des fuites inutiles d'informations sensibles.

Documentation API : Mettre à jour une question dans un quiz

Endpoint

PATCH /question/:quizId/:questionId

Description

Cet endpoint permet de mettre à jour une question spécifique dans un quiz existant. Les nouvelles informations de la question (texte, choix multiples, réponses, etc.) sont mises à jour dans la base de données.


En-têtes de la requête

Champ Type Requis Description
access_token string Oui Jeton d'accès au format Bearer <token>.

Paramètres de l'URL

Paramètre Type Requis Description
quizId string Oui Identifiant unique du quiz.
questionId number Oui Identifiant unique de la question à mettre à jour.

Corps de la requête

Champ Type Requis Description
text string Oui Texte de la question.
isMultipleChoice boolean Oui Indique si la question est à choix multiples.
answers tableau d'objets Oui Liste des réponses associées à la question.
- text string Oui Texte de la réponse.
- isCorrect boolean Non Indique si la réponse est correcte. Par défaut, false si non fourni.

Exemple de requête

{
  "text": "What is 2+3?",
  "isMultipleChoice": true,
  "answers": [
    { "text": "5", "isCorrect": true },
    { "text": "4" },
    { "text": "6" },
    { "text": "7" }
  ]
}

Fonctionnement

  1. Authentification : Vérifie que l'utilisateur est connecté et que le token d'accès est valide.
  2. Mise à jour : Met à jour la question avec les nouvelles informations dans la base de données, en liant la question à l'ID du quiz et de la question spécifiés.
  3. Renvoi : Retourne l'ID du quiz mis à jour.

Codes d'erreur possibles

Code HTTP Message Description
401 Unauthorized Le token d'accès est manquant ou invalide.
404 Not Found Le quiz ou la question spécifiés n'existent pas.
400 Bad Request Le corps de la requête est invalide ou incomplet.

Notes

  • Si une réponse ne contient pas isCorrect, elle sera considérée comme incorrecte (false) par défaut.
  • Assurez-vous que l'quizId et le questionId correspondent à des entrées valides dans la base de données.
  • Cette route est conçue pour des mises à jour précises des questions, en s'assurant que les réponses liées sont également mises à jour.

Documentation API : Stats Quiz

Endpoint

GET /quiz/stats/:id

Description

Cet endpoint permet de récupérer les statistiques d'un quiz, y compris le nombre de fois où il a été joué, le nombre de bonnes réponses, le nombre total de réponses, et le taux de réussite.

Exemple de réponse

{
  "totalRuns": 10,
  "correctAnswers": 50,
  "incorrectAnswers": 30,
  "totalAnswers": 80
}

Documentation API : Création Utilisateur

Endpoint

POST /user

Description

Cet endpoint permet de créer un nouvel utilisateur, avec des identifiants uniques.

Corps de la requête

Champ Type Requis Description
username string Oui Unique
email string Oui Unique
password string Oui

Exemple de requête

{
  "email": "arbre@gmail.com",
  "username": "yggdrasil",
  "password": "AAAHONMEMANGE"
}

Exemple de réponse

{
  "id": 1,
  "username": "yggdrasil",
  "email": "arbre@gmail.com"
}

Documentation API : Connexion Utilisateur

Endpoint

POST /auth/login

Description

Cet endpoint renvoie un cookie access_token permettant d'identifier l'utilisateur s'il renseigne ses identfifiants.


Corps de la requête

Champ Type Requis Description
login string Oui Nom d'utilisateur ou adresse e-mail
password string Oui Mot de passe

Exemple de requête

{
  "login": "yggdrasil",
  "password": "AAAHONMEMANGE"
}

Exemple de réponse

{
  "success": true
}

Documentation API : Infos Utilisateur

Endpoint

GET /user/:id

Description

Cet endpoint permet de récupérer les informations d'un utilisateur

Exemple de réponse

{
  "id": 1,
  "username": "yggdrasil",
  "email": "arbre@gmail.com",
  "stats": {
    "quizzesCreated": 2,
    "quizzesPlayed": 1,
    "correctAnswers": 0,
    "totalAnswers": 0
  }
}

Documentation API : Infos de l'utilisateur connecté

Endpoint

GET /user/me

Description

Cet endpoint renvoie les informations de l'utilisateur connecté, ou renvoie une erreur sinon.

Exemple de réponse

{
  "id": 1,
  "username": "yggdrasil",
  "email": "arbre@gmail.com",
  "stats": {
    "quizzesCreated": 2,
    "quizzesPlayed": 1,
    "correctAnswers": 0,
    "totalAnswers": 0
  }
}

Documentation API : Créer une Run

Endpoint

POST /run

Description

Cet endpoint permet de créer une nouvelle et retourne ses détails. L'identifiant de l'utilisateur est dans les cookies.

Corps de la requête

Champ Type Requis Description
quizId string Oui Identifiant du quiz

Exemple de requête

{
  "quizId": "16AX23"
}

Corps de la réponse

Champ Type Description
id number Identifiant unique de la run.
quizId string Identifiant du quiz associé.
quizUserId number Identifiant de l'utilisateur.
startDate string Date de début de la run.
lastChange string Date de la dernière modification.

Exemple de réponse

{
  "id": 2,
  "quizId": "34ZALL",
  "quizUserId": 1,
  "startDate": "2024-12-06T00:23:23.483Z",
  "lastChange": "2024-12-06T00:23:23.483Z"
}

Les autres endpoints sont identiques à ceux des routes /quiz.

Documentation API: Créer une partie

POST /party

Description

Cet endpoint permet de créer une nouvelle partie et retourne ses détails.

Corps de la requête

Champ Type Requis Description
quizId string Oui Identifiant du quiz
-------- ------ ------ -------------------

Exemple de requête

{
  "quizId": "16AX23"
}

Exemple de réponse

{
  "id": "CH36SF",
  "name": "New party",
  "quizId": "SY91WN",
  "status": "open"
}

Documentation API: Rejoindre une partie

GET /party/join/:party_id

Description

Cet endpoint permet à un utilisateur de rejoindre une partie existante.

Paramètres de l'URL

Paramètre Type Requis Description
party_id string Oui Identifiant de la partie

Réponse

La réponse ouvre un flux SSE (Server-Sent Events) pour recevoir des mises à jour en temps réel sur la partie.

Voici la liste des événements envoyés :

userJoined

Cet événement est envoyé lorsqu'un nouvel utilisateur rejoint la partie.

[
  {
    "id": 1,
    "username": "Thomas",
    "partyId": "693BCB",
    "isHost": true
  }
]

question

Cet événement est envoyé lorsqu'une nouvelle question est affichée.

{
  "id": 62,
  "text": "Which of these is NOT a catchphrase used by Rick Sanchez in the TV show \"Rick and Morty\"?",
  "type": "multiple",
  "categoryId": 2,
  "quizId": "SY91WN",
  "order": 0,
  "answers": [
    {
      "id": 209,
      "text": "Slam dunk, nothing but net!",
      "questionId": 62
    },
    {
      "id": 210,
      "text": "Hit the sack, Jack!",
      "questionId": 62
    },
    {
      "id": 211,
      "text": "Rikki-Tikki-Tavi, biatch!",
      "questionId": 62
    },
    {
      "id": 212,
      "text": "Wubba-lubba-dub-dub!",
      "questionId": 62
    }
  ],
  "category": {
    "id": 2,
    "name": "Entertainment: Cartoon &amp; Animations"
  }
}

answerRevealed

{
  "id": 62,
  "text": "Which of these is NOT a catchphrase used by Rick Sanchez in the TV show \"Rick and Morty\"?",
  "type": "multiple",
  "categoryId": 2,
  "quizId": "SY91WN",
  "order": 0,
  "answers": [
    {
      "id": 209,
      "text": "Slam dunk, nothing but net!",
      "fileType": "text",
      "isCorrect": true,
      "questionId": 62
    },
    {
      "id": 210,
      "text": "Hit the sack, Jack!",
      "fileType": null,
      "isCorrect": false,
      "questionId": 62
    }
  ],
  "category": {
    "id": 2,
    "name": "Entertainment: Cartoon &amp; Animations"
  }
}

endGame

[
  {
    "id": 1,
    "username": "Thomas",
    "score": 1
  }
]

Documentation API: Répondre à une question dans une partie

POST /party/answer

Exemple de requête

{
  "questionId": 62,
  "answerId": 209
}

Documentation API: Passer à la question suivante

GET /party/nextQuestion

Documentation API: Révéler la réponse

GET /party/revealAnswer

Documentation API: Score du joueur

GET /party/score

Exemple de réponse

{
  "score": 7
}