Web API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:The PeP5 application exposes a set of Web API endpoints primarily designed to support the secure PeP.ExamApp desktop client. These endpoints facilitate exam authorization, session management, and application updates. The backend also integrates with external APIs for specialized functionalities, such as code execution via the Piston API and content generation/evaluation using the OpenAI API.
The primary API controller for the desktop client is ExamAppController, which handles the entire lifecycle of an exam session from the student's perspective. Authentication is a prerequisite, managed through standard ASP.NET Core Identity login processes, which the ExamAppApiClient uses before interacting with the protected API endpoints.
Exam App API
The core API for the PeP.ExamApp client is located at the /api/exam-app route. It provides endpoints for checking application updates, retrieving exam information, and managing the authorization flow for starting a secure exam. All endpoints, except for /update, require the user to be authenticated with the Student role.
Sources: Controllers/ExamAppController.cs:8-13
Endpoints Summary
| Method | Path | Authentication | Description |
|---|---|---|---|
GET | /api/exam-app/update | Anonymous | Retrieves the latest update information for the Exam App client. |
GET | /api/exam-app/code/{code} | Student Role | Fetches details for a specific exam using an exam code. |
POST | /api/exam-app/authorize | Student Role | Authorizes a student for an exam using the exam code and a teacher's password. |
POST | /api/exam-app/start | Student Role | Starts an exam attempt using a previously obtained authorization token. |
Sources: Controllers/ExamAppController.cs:33-108
Exam Authorization and Start Flow
The following sequence diagram illustrates the complete flow from the PeP.ExamApp client to the backend API to start an exam.
This diagram shows the three main API calls required to successfully start an exam session.
Sources: Controllers/ExamAppController.cs:69-108, PeP.ExamApp/ExamAppApiClient.cs:61-100, PeP.ExamApp/Pages/TeacherAuthPage.xaml.cs:38-63
GET /api/exam-app/update
This endpoint allows the PeP.ExamApp client to check for new versions. It reads update information directly from the application's configuration file (appsettings.json).
The response body is a JSON object with the following structure:
| Field | Type | Description |
|---|---|---|
Version | string | The latest version number (e.g., "1.1.0"). |
DownloadUrl | string | URL to the new installer executable. |
ReleaseNotes | string | Notes for the new release. |
ReleaseDate | DateTime | The date the update was released. |
IsMandatory | bool | If true, the update cannot be skipped. |
MinimumVersion | string | The minimum required client version. |
Checksum | string | SHA256 checksum of the installer file for verification. |
Sources: Controllers/ExamAppController.cs:33-59, PeP.ExamApp/Installer/README.md:65-76
The configuration in appsettings.json is structured as follows:
{
"ExamAppUpdate": {
"Version": "1.1.0",
"DownloadUrl": "https://yourserver.com/downloads/PeP.ExamApp_Setup_1.1.0.exe",
"ReleaseNotes": "- Bug fixes\n- Performance improvements",
"ReleaseDate": "2025-12-22",
"IsMandatory": false,
"MinimumVersion": "1.0.0",
"Checksum": "sha256hashofinstallerfile"
}
}
Sources: PeP.ExamApp/Installer/README.md:78-88
POST /api/exam-app/authorize
This endpoint validates an exam code and a teacher's password to generate a short-lived authorization token. This token is required to start the exam.
Request Body (AuthorizeRequest)
public record AuthorizeRequest(string? Code, string? TeacherPassword);
Response Body (AuthorizeResponse)
public record AuthorizeResponse(bool Success, string? Error, string? AuthorizationToken, DateTime? ExpiresAtUtc, ExamAppExamInfo? Exam);
Sources: Controllers/ExamAppController.cs:81-93, Controllers/ExamAppController.cs:112-114
POST /api/exam-app/start
Once authorized, the client uses the authorization token to start the exam. This creates an ExamAttempt or ProgrammingExamAttempt record in the database and returns a final launchToken for the exam session.
Request Body (StartRequest)
public record StartRequest(string? AuthorizationToken);
Response Body (StartResponse)
public record StartResponse(bool Success, string? Error, int? AttemptId, string? LaunchToken, DateTime? ExpiresAtUtc, bool IsProgrammingExam);
Sources: Controllers/ExamAppController.cs:95-108, Controllers/ExamAppController.cs:116-117
External API Integrations
The backend leverages external services to provide advanced features like code execution and AI-driven content management.
Piston API for Code Execution
The CodeExecutionService is responsible for running student code against test cases. It uses the Piston API, a public service for code execution.
The service constructs a PistonExecuteRequest and sends it to https://emkc.org/api/v2/piston/execute.
This diagram shows the process of executing code via the Piston API.
Sources: Services/CodeExecutionService.cs:150-288
The request payload sent to the Piston API is defined by the PistonExecuteRequest class.
| Field | Type | Description |
|---|---|---|
Language | string | The programming language (e.g., "python"). |
Version | string | The specific version of the language (e.g., "3.10.0"). |
Files | List | A list of files, each with a Name and Content. |
Stdin | string? | Standard input to be passed to the program. |
RunTimeout | int | Execution timeout in milliseconds. |
Sources: Services/CodeExecutionService.cs:56-78
OpenAI API for Content Generation and Evaluation
The OpenAIService integrates with the OpenAI API to perform two main functions:
- Generate Exam Questions: Creates multiple-choice or programming tasks based on a topic, difficulty, and other parameters.
- Evaluate Student Code: Reviews student code for a programming task and provides a score, feedback, and suggestions.
The service retrieves the API key and model name from PlatformSettings in the database.
Sources: Services/OpenAIService.cs:111-120, Services/OpenAIService.cs:511-521
AI Code Evaluation
When evaluating code, the OpenAIService.EvaluateCodeAsync method constructs a detailed system prompt that instructs the AI model on how to act as a code reviewer. It specifies grading principles, scoring guidelines, and the exact JSON structure for the response.
The final evaluation is captured in the AICodeEvaluation class.
| Field | Type | Description |
|---|---|---|
TaskId | int | The ID of the task being evaluated. |
Score | decimal | The final score awarded for the task. |
MaxScore | decimal | The maximum possible score for the task. |
CodeQualityScore | decimal | A score from 0-100 for code quality. |
CorrectnessScore | decimal | A score from 0-100 for correctness. |
EfficiencyScore | decimal | A score from 0-100 for efficiency. |
CompletionPercentage | decimal | The percentage of requirements met (0-100). |
Feedback | string | Detailed constructive feedback. |
Strengths | string | What the student did well. |
AreasForImprovement | string | Specific suggestions for improvement. |
SolutionSuggestion | string | A brief explanation of a better solution. |
CodeSnippets | List | A list of specific code snippets with comments. |
Sources: Services/OpenAIService.cs:22-38