Skip to content

Formation API

Jump to bottom
Robin Lafontaine edited this page Feb 13, 2025 · 19 revisions

API Documentation

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

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)

Allowed Role

USER, ADMIN

Parameters

None

Responses

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

Example cURL

curl -L -X GET 'http://localhost/v1/formation/formations' \
-H 'Authorization: Bearer {jwt}'
GET /formation/{formationId} (gets details about the formation requested)

Allowed Role

USER, ADMIN

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/v1/formation/{formationId}' \
-H 'Authorization: Bearer {jwt}'

Quiz Endpoints

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

Allowed Role

USER, ADMIN

Parameters

None

Responses

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

Example cURL

curl -L -X GET 'http://localhost/v1/formation/quizzes' \
-H 'Authorization: Bearer {jwt}'
GET /formation/quiz/{quizId} (gets details about the quiz requested)

Allowed Role

USER, ADMIN

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/v1/formation/quiz/{quizId}' \
-H 'Authorization: Bearer {jwt}'
POST /formation/quiz/score (save user score for a quiz)

Allowed Role

USER, ADMIN

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/v1/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)

Allowed Role

USER, ADMIN

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/v1/formation/quizzes/scores' \
-H 'Authorization: Bearer {jwt}'
GET /formation/quiz/score/{quiz_id} (gets the selected quiz score of the connected user)

Allowed Role

USER, ADMIN

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

Example cURL

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

Video Endpoints

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

Allowed Role

USER, ADMIN

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/v1/formation/videos' \
-H 'Authorization: Bearer {jwt}'
POST /formation/video/watched/{videoId} (marks a video as watched for the connected user)

Allowed Role

USER, ADMIN

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/v1/formation/video/watched/1' \
-H 'Authorization: Bearer {jwt}'
GET /formation/videos/watched (gets all videos watched by the connected user)

Allowed Role

USER, ADMIN

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/v1/formation/videos/watched' \
-H 'Authorization: Bearer {jwt}'

Badge Endpoints

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

Allowed Role

USER, ADMIN

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

Example cURL

curl -L -X POST 'http://localhost/v1/formation/badge/claim/1' \
-H 'Authorization: Bearer {jwt}'
GET /formation/badge/all (gets all badges for the connected user)

Allowed Role

USER, ADMIN

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/v1/formation/badge/all' \
-H 'Authorization: Bearer {jwt}'
GET /formation/badge/{badgeId} (gets details about the badge requested)

Allowed Role

USER, ADMIN

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", ...}

Example cURL

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

Admin Endpoints

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

Allowed Role

ADMIN

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/v1/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)

Allowed Role

ADMIN

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/v1/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)

Allowed Role

ADMIN

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/v1/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)

Allowed Role

ADMIN

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/v1/admin/formation/video/{videoId}' \
-H 'Authorization: Bearer {jwt}'
POST /admin/formation/upload (upload a file)

Allowed Role

ADMIN

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/v1/admin/formation/upload' \
-H 'Authorization: Bearer {jwt}' \
-F 'file=@/path/to/file'

Menu

Clone this wiki locally