Aller au contenu

API — Notifications

Ce document décrit les endpoints de l'API REST pour la gestion des notifications in-app (domain Notification).

Base URL

Tous les endpoints sont préfixés par /api/v1. Authentification JWT requise.

Endpoints

GET /notifications — Lister les notifications

Retourne la liste paginée des notifications de l'utilisateur connecté, triées par date décroissante.

Paramètre Type Description
page integer Numéro de page (défaut : 1) 
{
  "data": [
    {
      "id": 1,
      "type": "game_joined",
      "title": "Nouveau joueur",
      "message": "Jean a rejoint la partie",
      "data": { "game_id": 42, "actor_id": 5 },
      "is_read": false,
      "read_at": null,
      "created_at": "2026-03-08T14:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1,
    "unread_count": 1
  }
}

{ "message": "Unauthenticated." }

GET /notifications/unread-count — Compteur de non lues

Retourne le nombre de notifications non lues de l'utilisateur connecté.

{ "unread_count": 5 }

POST /notifications/{id}/read — Marquer comme lue

Marque une notification comme lue. L'utilisateur doit être le propriétaire de la notification.

Paramètre Type Description
id integer ID de la notification 
{
  "data": {
    "id": 1,
    "type": "game_joined",
    "title": "Nouveau joueur",
    "message": "Jean a rejoint la partie",
    "data": { "game_id": 42 },
    "is_read": true,
    "read_at": "2026-03-08T15:00:00+00:00",
    "created_at": "2026-03-08T14:00:00+00:00"
  }
}

{ "message": "Cette notification ne vous appartient pas." }

POST /notifications/read-all — Tout marquer comme lu

Marque toutes les notifications non lues de l'utilisateur comme lues.

{
  "message": "Toutes les notifications ont été marquées comme lues.",
  "count": 3
}

DELETE /notifications/{id} — Supprimer

Supprime une notification. L'utilisateur doit être le propriétaire.

Paramètre Type Description
id integer ID de la notification 
{ "message": "Notification supprimée." }

{ "message": "Cette notification ne vous appartient pas." }

Types de notifications

Type Catégorie Déclencheur
game_joined Matchs Un joueur rejoint la partie
game_left Matchs Un joueur quitte la partie
game_cancelled Matchs Le créateur annule la partie
game_full Matchs La partie est complète (4/4)
game_reminder Matchs Rappel avant la partie
game_started Matchs La partie a commencé
score_submitted Scores Un joueur soumet le score
score_validated Scores Un joueur valide le score
score_contested Scores Un joueur conteste le score
score_finalized Scores Le score est finalisé

Modèle de données

notifications
├── id              (bigint, PK)
├── user_id         (bigint, FK → users)
├── type            (string)
├── title           (string)
├── message         (text)
├── data            (json, nullable)
├── read_at         (timestamp, nullable)
├── created_at      (timestamp)
└── updated_at      (timestamp)

Index: (user_id, read_at), (user_id, created_at)