API REST

Préfixe proposé : /api. Corps JSON avec Content-Type: application/json. Utiliser HTTPS et WSS en environnement déployé.

Les routes protégées exigent Authorization: Bearer <token>. Le token provient de la connexion REST ; sa durée et sa révocation restent à définir. Les lectures publiques exposent seulement l’état public des parties et les statistiques de jeu.

Méthode	Endpoint proposé	Authentification	Fonction et réponse normale
POST	/api/users	Non	Créer un compte ; 201, username
POST	/api/auth/login	Non	Authentifier ; 200, token et username
GET	/api/users/me	Oui	Lire son compte ; 200, username
PATCH	/api/users/me	Oui	Modifier son username et/ou mot de passe ; 200, username actualisé
GET	/api/matches	Non	Lister les parties consultables ; 200, tableau de résumés
GET	/api/matches/{uid}	Non	Lire l’état courant ou le résultat sauvegardé ; 200, partie publique
GET	/api/matches/{uid}/stats	Non	Lire les statistiques par joueur ; 200, valeurs provisoires ou finales
GET	/api/users/{username}/stats	Non	Lire les statistiques cumulées des parties finalisées ; 200, compteurs agrégés

Comptes et authentification

Requête POST /api/users, puis réponse 201 :

{ "username": "alice", "password": "exemple-mot-de-passe" }

{ "username": "alice" }

Le backend calcule passhash pour le stockage et refuse un username déjà utilisé. Le mot de passe est transmis uniquement dans la requête HTTPS, jamais en réponse.

POST /api/auth/login reçoit les mêmes champs. Réponse 200 :

{ "token": "jeton-exemple", "username": "alice" }

GET /api/users/me renvoie {"username":"alice"}. PATCH /api/users/me accepte un sous-ensemble non vide de username et password, par exemple :

{ "password": "nouveau-mot-de-passe" }

Seul le compte authentifié est modifié. Un renommage pendant l’appartenance à une partie active est refusé avec 409, car les événements identifient les joueurs par username. La gestion d’un renommage dans les résultats historiques reste à préciser, sans changement de schéma dans cette tâche.

Parties et statistiques

Réponse GET /api/matches :

[{ "matchUid": "match_123", "state": "ROUND_ONGOING", "roundNumber": 2 }]

Réponse GET /api/matches/match_123 : instantané complet de référence. Les HP, coordonnées, couleurs et IDs d’équipe ci-dessous sont illustratifs.

{
	"matchUid": "match_123",
	"state": "ROUND_ONGOING",
	"roundNumber": 2,
	"players": [
		{
			"username": "alice",
			"teamId": 1,
			"position": { "x": 12.5, "y": 0, "z": 8.2 },
			"rotation": { "x": 0, "y": 90, "z": 0 },
			"hp": 100
		},
		{
			"username": "bob",
			"teamId": 1,
			"position": { "x": 10, "y": 0, "z": 8 },
			"rotation": { "x": 0, "y": 90, "z": 0 },
			"hp": 100
		},
		{
			"username": "chloe",
			"teamId": 2,
			"position": { "x": 20, "y": 0, "z": 8 },
			"rotation": { "x": 0, "y": 270, "z": 0 },
			"hp": 0
		},
		{
			"username": "david",
			"teamId": 2,
			"position": { "x": 22, "y": 0, "z": 8 },
			"rotation": { "x": 0, "y": 270, "z": 0 },
			"hp": 40
		}
	],
	"teams": [
		{ "teamId": 1, "color": "bleu", "players": ["alice", "bob"], "score": 1 },
		{ "teamId": 2, "color": "rouge", "players": ["chloe", "david"], "score": 0 }
	]
}

Pour une partie terminée, positions, rotations et HP peuvent être omis s’ils ne sont plus disponibles ; l’état reste MATCH_ENDED, avec équipes et scores persistés.

Réponse GET /api/matches/match_123/stats :

{
	"matchUid": "match_123",
	"state": "ROUND_ONGOING",
	"players": [
		{ "username": "alice", "stats": { "damage": 100, "kills": 1, "deaths": 0, "matchTime": 85, "aliveTime": 85 } },
		{ "username": "bob", "stats": { "damage": 0, "kills": 0, "deaths": 0, "matchTime": 85, "aliveTime": 85 } },
		{ "username": "chloe", "stats": { "damage": 0, "kills": 0, "deaths": 1, "matchTime": 85, "aliveTime": 70 } },
		{ "username": "david", "stats": { "damage": 0, "kills": 0, "deaths": 0, "matchTime": 85, "aliveTime": 85 } }
	]
}

Ces valeurs sont provisoires tant que la partie n’est pas MATCH_ENDED. Réponse GET /api/users/alice/stats : somme des cinq compteurs des parties finalisées, avec les mêmes noms et unités.

{ "username": "alice", "stats": { "damage": 320, "kills": 3, "deaths": 1, "matchTime": 240, "aliveTime": 200 } }

Statuts HTTP

Code	Situation
200	Lecture, connexion ou modification réussie
201	Compte créé
400	JSON, champs, types ou valeurs invalides
401	Identifiants incorrects ou token absent, invalide ou expiré sur une route protégée
403	Action interdite à l’identité authentifiée
404	Partie ou utilisateur introuvable
409	Username déjà pris ou renommage incompatible avec une partie active
500	Erreur interne, sans détails techniques ni secrets dans la réponse

Les erreurs REST utilisent aussi l’objet type: "error" et data: {code, message} décrit dans Erreurs et reconnexion. Les codes complémentaires proposés sont INVALID_PAYLOAD, USER_NOT_FOUND, USERNAME_TAKEN et USERNAME_CHANGE_FORBIDDEN.