Formation API

API Documentation

This documentation provides details about all available endpoints related to formations, quizzes, videos, and badges. Endpoints are grouped into the following categories:

• Formation Endpoints
• Quiz Endpoints
• Video Endpoints
• Badge Endpoints

Note: The user's email is extracted from the JWT, so there is no need to supply it via a header.

---

Formation Endpoints

GET /formation/formations (gets all in-memory formations details)

Parameters

None

Responses

HTTP Code	Content-Type	Response
200	json	[{"id": int, "name": "string", "description": "string", ...}, ...]

Example cURL

curl -L -X GET 'http://localhost:8080/formation/formations' \
-H 'Authorization: Bearer {jwt}'

GET /formation/{formationId} (gets details about the formation requested)

Parameters

Name	Type	Data Type	Description
formationId	required	int	The specific formation id

Responses

HTTP Code	Content-Type	Response
200	json	{"id": int, "name": "string", "description": "string", ...}
404	string	Formation not found

Example cURL

curl -L -X GET 'http://localhost:8080/formation/{formationId}' \
-H 'Authorization: Bearer {jwt}'

---

Quiz Endpoints

GET /formation/quizzes (gets all in-memory quizzes details)

Parameters

None

Responses

HTTP Code	Content-Type	Response
200	json	[{"id": int, "json": "string", ...}, ...]

Example cURL

curl -L -X GET 'http://localhost:8080/formation/quizzes' \
-H 'Authorization: Bearer {jwt}'

GET /formation/quiz/{quizId} (gets details about the quiz requested)

Parameters

Name	Type	Data Type	Description
quizId	required	int	The specific quiz id

Responses

HTTP Code	Content-Type	Response
200	json	{"id": int, "json": "string", ...}
404	string	Quiz not found

Example cURL

curl -L -X GET 'http://localhost:8080/formation/quiz/{quizId}' \
-H 'Authorization: Bearer {jwt}'

POST /formation/quiz/score (save user score for a quiz)

Parameters

The request body must be a JSON object containing:

Name	Type	Data Type	Description
userEmail	required	string	The email of the user (extracted from JWT)
quizId	required	int	The id of the quiz
score	required	float	The score (must be between 0 and 1)

Responses

HTTP Code	Content-Type	Response
200	string	Score saved successfully
400	string	Invalid request or Score must be between 0 and 1
500	string	Error saving score

Example cURL

curl -L -X POST 'http://localhost:8080/formation/quiz/score' \
-H 'Authorization: Bearer {jwt}' \
-H 'Content-Type: application/json' \
--data-raw '{"quizId": 1, "score": 0.8}'

GET /formation/quizzes/scores (gets all the quiz scores of the connected user)

Parameters

None (User email is extracted from the JWT)

Responses

HTTP Code	Content-Type	Response
200	json	[{"userEmail": "string", "quizId": int, "score": float}, ...]
404	N/A	Not Found (if no scores exist)

Example cURL

curl -L -X GET 'http://localhost:8080/formation/quizzes/scores' \
-H 'Authorization: Bearer {jwt}'

GET /formation/quiz/score/{quiz_id} (gets the selected quiz score of the connected user)

Parameters

Name	Type	Data Type	Description
quiz_id	required	int	The specific quiz id

Responses

HTTP Code	Content-Type	Response
200	json	The score as a float
404	string	Score not found

Example cURL

curl -L -X GET 'http://localhost:8080/formation/quiz/score/{quiz_id}' \
-H 'Authorization: Bearer {jwt}'

---

Video Endpoints

GET /formation/videos (gets all in-memory videos details)

Parameters

None

Responses

HTTP Code	Content-Type	Response
200	json	[{"id": int, "title": "string", "description": "string", "url": "string", ...}, ...]

Example cURL

curl -L -X GET 'http://localhost:8080/formation/videos' \
-H 'Authorization: Bearer {jwt}'

POST /formation/video/watched/{videoId} (marks a video as watched for the connected user)

Parameters

Name	Type	Data Type	Description
videoId	required	int	The specific video id

Responses

HTTP Code	Content-Type	Response
200	string	Video watched
404	string	Video not found

Example cURL

curl -L -X POST 'http://localhost:8080/formation/video/watched/1' \
-H 'Authorization: Bearer {jwt}'

GET /formation/videos/watched (gets all videos watched by the connected user)

Parameters

None (User email is extracted from the JWT)

Responses

HTTP Code	Content-Type	Response
200	json	[{"id": int, "title": "string", "description": "string", "url": "string", ...}, ...]

Example cURL

curl -L -X GET 'http://localhost:8080/formation/videos/watched' \
-H 'Authorization: Bearer {jwt}'

---

Badge Endpoints

POST /formation/badge/claim/{badgeId} (claim a badge for the connected user)

Parameters

Name	Type	Data Type	Description
badgeId	required	int	The specific badge id

Responses

HTTP Code	Content-Type	Response
200	json	JSON representation of the claimed badge
404	string	Badge not found

Example cURL

curl -L -X POST 'http://localhost:8080/formation/badge/claim/1' \
-H 'Authorization: Bearer {jwt}'

GET /formation/badge/all (gets all badges for the connected user)

Parameters

None (User email is extracted from the JWT)

Responses

HTTP Code	Content-Type	Response
200	json	[{"id": int, "name": "string", "description": "string", ...}, ...]

Example cURL

curl -L -X GET 'http://localhost:8080/formation/badge/all' \
-H 'Authorization: Bearer {jwt}'

GET /formation/badge/{badgeId} (gets details about the badge requested)

Parameters

Name	Type	Data Type	Description
badgeId	required	int	The specific badge id

Responses

HTTP Code	Content-Type	Response
200	json	{"id": int, "name": "string", "description": "string", ...}
404	string	Badge not found

Example cURL

curl -L -X GET 'http://localhost:8080/formation/badge/1' \
-H 'Authorization: Bearer {jwt}'

---

Admin Endpoints

For the /admin/formation/** endpoints, the allowed roles are ADMIN.

PUT /admin/formation/quiz/{quizId} (update a quiz)

Parameters

Name	Type	Data Type	Description
quizId	required	int	The specific quiz id
quiz	required	JSON	The quiz details to update

Responses

HTTP Code	Content-Type	Response
200	string	Quiz updated successfully
404	string	Quiz not found

Example cURL

curl -L -X PUT 'http://localhost:8080/admin/formation/quiz/{quizId}' \
-H 'Authorization: Bearer {jwt}' \
-H 'Content-Type: application/json' \
--data-raw '{"json": "updated quiz details"}'

POST /admin/formation/quiz (create a quiz)

Parameters

Name	Type	Data Type	Description
quiz	required	JSON	The quiz details to create

Responses

HTTP Code	Content-Type	Response
200	string	Quiz created successfully

Example cURL

curl -L -X POST 'http://localhost:8080/admin/formation/quiz' \
-H 'Authorization: Bearer {jwt}' \
-H 'Content-Type: application/json' \
--data-raw '{"json": "new quiz details"}'

POST /admin/formation/video/upload (upload a video)

Parameters

Name	Type	Data Type	Description
videoFile	required	file	The video file to upload
thumbnailFile	required	file	The thumbnail file to upload
captionFile	optional	file	The caption file to upload
title	required	string	The title of the video
description	required	string	The description of the video

Responses

HTTP Code	Content-Type	Response
200	string	Video uploaded successfully
500	string	Error uploading video

Example cURL

curl -L -X POST 'http://localhost:8080/admin/formation/video/upload' \
-H 'Authorization: Bearer {jwt}' \
-F 'videoFile=@/path/to/video.mp4' \
-F 'thumbnailFile=@/path/to/thumbnail.jpg' \
-F 'captionFile=@/path/to/caption.vtt' \
-F 'title=Video Title' \
-F 'description=Video Description'

DELETE /admin/formation/video/{videoId} (delete a video)

Parameters

Name	Type	Data Type	Description
videoId	required	int	The specific video id

Responses

HTTP Code	Content-Type	Response
200	string	Video deleted successfully
404	string	Video not found

Example cURL

curl -L -X DELETE 'http://localhost:8080/admin/formation/video/{videoId}' \
-H 'Authorization: Bearer {jwt}'

POST /admin/formation/upload (upload a file)

Parameters

Name	Type	Data Type	Description
file	required	file	The file to upload

Responses

HTTP Code	Content-Type	Response
200	string	The URL of the uploaded file
500	string	Error uploading file

Example cURL

curl -L -X POST 'http://localhost:8080/admin/formation/upload' \
-H 'Authorization: Bearer {jwt}' \
-F 'file=@/path/to/file'