You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/docs/backend/quickstart/backend.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
### Development server
6
6
7
-
After setting up your development workspace in the main guide, you can launch a Django development server by running `python manage.py runserver`. Note you must have the virtual environment activated for this to work.
7
+
After setting up your development workspace in the main guide, you can launch a Django development server by running `python manage.py runserver`. Note that you must have the virtual environment activated for this to work.
Copy file name to clipboardExpand all lines: documentation/docs/backend/quickstart/frontend.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
### Development server
6
6
7
-
After setting up your development workspace in the main guide, you can launch a Django development server by running `yarn dev`. Note you must have the virtual environment activated for this to work.
7
+
After setting up your development workspace in the main guide, you can launch a Django development server by running `yarn dev`. Note that you must have the virtual environment activated for this to work.
The quiz_take app provides backend endpoints for the frontend to access using a REST API.
6
+
7
+
## Endpoints
8
+
9
+
All API endpoints have the root URL `/api/take-quiz/`; i.e. when a certain endpoint is stated to be located at `endpoint/location/`, it is actually located at `/api/take-quiz/endpoint/location/` or, more fully, `localhost:8081/api/take-quiz/endpoint/location/` where `localhost:8081` is where the Django backend is being hosted. Django's [captured value notation](https://docs.djangoproject.com/en/4.0/topics/http/urls/#example) is used in these docs. `pk` is an abbreviation for "primary key", which is essentially an ID assigned to objects stored in the database.
10
+
11
+
### Question Detail
12
+
13
+
Located at `question/<int:question_pk>/`. Provides support for GET requests to fetch the details of a specific question.
14
+
15
+
### Answers List
16
+
17
+
Located at `question/<int:question_pk>/answers/`. Provides support for GET requests to fetch a list of Answers associated with a specific question.
18
+
19
+
### Answer Detail
20
+
21
+
Located at `question/<int:question_pk>/answers/<int:answer_pk>/`. Provides support for GET requests to fetch the details of a specific Answer associated with a specific question.
22
+
23
+
### Topics List
24
+
25
+
Located at `question/<int:question_pk>/topics/`. Provides support for GET requests to fetch a list of Topics associated with a specific question.
26
+
27
+
### Topic Detail
28
+
29
+
Located at `question/<int:question_pk>/topics/<int:topic_pk>/`. Provides support for GET requests to fetch the details of a specific Topic associated with a specific question.
30
+
31
+
### Subject Detail
32
+
33
+
Located at `question/<int:question_pk>/subject/`. Provides support for GET requests to fetch the details of the subject that a specific question belongs to.
34
+
35
+
### Question Response Create
36
+
37
+
Located at `submit/question_response/`. Provides support for POST requests to create a QuestionResponse. Included in this response will be details such as the User submitting it, the question to which they are responding, and their selected Answer (all of which will be passed as primary keys referencing an object in the database). This endpoint should be used whenever a user submits a question (or more specifically, once they have submitted it such that they cannot change their response; depending on the frontend implementation, this may mean that many QuestionResponses are submitted at the end of a quiz [if the user can go back and change answers to previous questions while doing the quiz], or that one QuestionResponse is submitted whenever they answer a question [if the user cannot go back and change their answers while doing the quiz]).
38
+
39
+
### Quiz Statistics Create
40
+
41
+
Located at `submit/quiz_statistics/`. Provides support for POST requests to create a [QuizStatistics](./shared_models.md) object. This endpoint should be used when a user has completed a quiz, to send details about the quiz they just completed to the database (for later use on their user dashboard).
42
+
43
+
## Testing
44
+
45
+
Unit tests can be run from within the backend Docker container using the command `python manage.py test` (more verbosely if executing from a terminal not SSH'd into the container: `docker exec -it elucidate_server python manage.py test`). Ensure you are executing the command from the same directory as `manage.py`.
Copy file name to clipboardExpand all lines: documentation/docs/backend/quiz/shared_models.md
+12-15Lines changed: 12 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,28 +10,25 @@ The `shared_models` app is designed to hold the models and serializers that need
10
10
11
11
There are four shared quiz models:
12
12
13
-
* Question - a model representing a generic quiz question. Questions come in three types (represented by the `question_type` field): multiple choice, numerical answer and short answer.
14
-
*Topic - a model representing a specific subject topic. Topics can be attached to many Questions (and each Question may have many associated topics). topics will be able to be created and modified by admins for regular users to use to tag their questions.
15
-
*Subject - a model representing a school subject. There can be many topics for one subject. Subjects are not connected to questions, as it is simpler for the backend to derive the subjects from the topics instead of having both topics and subjects connected to a question which complicates things. Subjects can also be created and modified by admins.
13
+
* Question - a model representing a generic quiz question. Questions come in three types (represented by the `question_type` field): multiple choice, numerical answer and short answer. Each question has a numeric `marks` field, used to weight the question compared to others and give an estimation of its complexity/difficulty. There is also an `is_verified` field, which has a default value of False. Whenever a user submits a question, it will thus be unverified and will not appear in question pools when generating quizzes. Admins can access the admin dashboard and filter questions by their `is_verified` status, and manually approve (and modify if necessary) submitted questions.
14
+
*Subject - a model representing an ATAR subject and unit (e.g., Methods Unit 3, Chemistry Unit 1, Specialist Unit 4, Physics Unit 2, etc.). Each Question will have exactly one subject attached to it. subjects can be created, modified and deleted by admins only.
15
+
*Topic - a model representing a specific topic of a given subject (e.g., the subject "Methods Unit 3" might have the Topics "Differentiation", "Integration", "Logarithms", etc.). Each Topic is associated to a subject and the Topics for each subject will be different (e.g., the subject "English Unit 1" may have the Topics "Poetry", "Creative Writing" and "Prose", whereas the subject "Chemistry Unit 3" may have the topics "Redox Reactions", "Proteins" and "Equilibrium"). Each Question may have zero, one or many Topics attached to it. Topics will be able to be created and modified by admins for regular users to use to tag their Questions.
16
16
* Answer - a model representing an answer associated with a particular Question. Each Question can have multiple associated answers. Each answer can be marked as being correct or incorrect. For the three different types of Question, the intended use of the Answer model varies:
17
-
* For multiple choice questions, each Answer will appear as an option for the user taking the quiz to select. One or more Answers will be correct, and the remaining Answers will be incorrect.
18
-
* For numerical answer questions, no options will be displayed, and the user must enter a numerical value into a text field. Each of the Answers associated with such a Question should have `is_correct = True`, and if the user's input matches any of these answers, they will be marked correct. Answers which have `is_correct = False` will not do anything and hence **should not be added** to numerical answer questions.
19
-
* For short answer questions, the user will be given an extended text field to enter their answer into. Due to the nature of this question, automated marking is not possible, and so the user will have to self-mark their response. Upon submitting their answer, all Answers associated to the Question with `is_correct = True` will be displayed for the user to compare their response to. As with numerical answer questions, Answers with `is_correct = False` will not do anything and hence **should not be added**.
17
+
* For multiple choice questions, each answer will appear as an option for the user taking the quiz to select. One or more answers will be correct, and the remaining answers will be incorrect.
18
+
* For numerical answer questions, no options will be displayed, and the user must enter a numerical value into a text field. Each of the answers associated with such a Question should have `is_correct = True`, and if the user's input matches any of these answers, they will be marked correct. Answers which have `is_correct = False` will not do anything and hence **should not be added** to numerical answer questions.
19
+
* For short answer questions, the user will be given an extended text field to enter their answer into. Due to the nature of this question, automated marking is not possible, and so the user will have to self-mark their response. Upon submitting their answer, all answers associated to the Question with `is_correct = True` will be displayed for the user to compare their response to. As with numerical answer questions, answers with `is_correct = False` will not do anything and hence **should not be added**.
20
20
21
21
### Statistics
22
22
23
-
* QuizStatistics - a model representing a response to a Quiz submitted by a User, stored in the database for statistics purposes. The QuizStatistics model contains all of the necessary data for the following statistics to be surmised, as per the client's requirements:
24
-
* How many questions the quiz has
25
-
* Total marks and the user's mark
26
-
* How long the User took to complete the Quiz
27
-
* When the quiz was taken
28
-
* How many Users in total have attempted a given Quiz
29
-
* The average score (across all Users) for a given Question
30
-
* The average score (across all Users) for a given Tag (i.e. subject and topic)
23
+
* QuestionResponse - a model representing a response to a Question submitted by a User, stored in the database for statistics purposes. It stores the User that submitted the response, the Question they attempted, the answer they selected, and the date and time at which they submitted the response. This model is used for calculating properties in other statistics models. It also essentially constitutes the raw data of the system, so can be in principle extracted for deeper statistical analysis.
24
+
* UserStatistics - a model representing various statistics concerning a specific User, to be displayed on their user dashboard. Includes the number of quizzes they have completed, the number of questions the User has created, and their average score (over all the questions they have ever answered).
25
+
* QuizStatistics - a model representing various data relating to a quiz taken by a specific User, to be displayed on their user dashboard. Includes the quiz title, subject, topics, date taken, and score achieved for the quiz. Here, "quiz" refers to an ad-hoc quiz created by a user for revision purposes.
26
+
* QuestionStatistics - a model representing various statistics concerning a specific Question, for admin perusal. Includes a reference to the Question at hand, the total number of users who have attempted the question, and the average score (across all users who have attempted) for the question.
27
+
* TopicStatistics - a model representing various statistics concerning all questions falling under a specific Topic, for admin perusal. Includes a reference to the Topic at hand, and the average score (across all the attempts at all the questions under this topic) for the topic.
31
28
32
29
## Serializers
33
30
34
-
The `shared_models` app provides serializers for each of the above models.
31
+
The `shared_models` app provides primary key serializers (`ModelSerializer`s) for each of the above models. The serializers provide `create` methods where necessary.
This API is used to manage the user lifecycle. It allows us to:
5
4
6
5
* Retrieve both a list of registered users, or a single user
7
6
* Register a user
8
7
* Update user information
9
8
* Delete a user
10
9
11
-
----
12
-
**URL:**
10
+
## URL
13
11
14
-
_/users_
12
+
`/users`
15
13
16
-
----
17
-
**Methods:**
14
+
## Methods
18
15
19
16
`GET` | `POST` | `DELETE` | `PUT`
20
17
21
-
----
22
-
**URL Params:**
18
+
## URL Parameters
23
19
24
20
| URL | Method | Description |
25
21
| :--- | :----: | :--- |
@@ -29,13 +25,11 @@ _/users_
29
25
|_/users/[id]_|`PUT`| Updates an existing users details |
30
26
|_/users/[id]_|`DELETE`| Deletes an existing user from the database |
31
27
32
-
----
33
-
**Required:**
28
+
## Required
34
29
35
30
`id=[integer]`
36
31
37
-
----
38
-
**Data Params:**
32
+
## Data Parameters
39
33
40
34
| Key | Data Type | Description |
41
35
| :---- | :----: | :--- |
@@ -44,50 +38,51 @@ _/users_
44
38
45
39
**_More to come!_**
46
40
47
-
----
48
-
**Success Response:**
41
+
## Success Response
49
42
50
-
<_What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect!_>
43
+
<_What should the status code be on success and is there any returned data? This is useful when people need to know what their callbacks should expect!_>
51
44
52
-
***Code:** 200 OK<br />
53
-
**Content:** <br />
54
-
```
45
+
***Code:** 200 OK
55
46
47
+
**Content:**
48
+
49
+
```json
56
50
{
57
51
"url": "http://127.0.0.1:8000/users/1/",
58
52
"username": "foo",
59
53
"email": "foo@bar.com",
60
54
"groups": []`
61
55
}
62
-
```
56
+
```
63
57
64
58
**_More to come_**
65
59
66
-
----
67
-
**Error Response:**
60
+
## Error Response
61
+
62
+
***Code:** 403 FORBIDDEN
68
63
69
-
* **Code:** 403 FORBIDDEN <br />
70
64
**Content:**`{ detail: "Authentication credentials were not provided." }`
71
65
72
66
OR
73
67
74
-
* **Code:** 400 BAD REQUEST <br />
68
+
***Code:** 400 BAD REQUEST
69
+
75
70
**Content:**`{ "username": ["A user with that username already exists."] }`
76
71
77
72
OR
78
73
79
-
* **Code:** 400 BAD REQUEST <br />
74
+
***Code:** 400 BAD REQUEST
75
+
80
76
**Content:**`{ "username": ["This field may not be blank."] }`
81
77
82
-
----
83
-
**Sample Call:**
78
+
## Sample Call
84
79
85
-
_Still to do_
80
+
**_Still to do_**
86
81
87
-
**Notes:**
82
+
## Notes
88
83
89
84
* Still to do:
90
-
* Need to workout how to make sure it checks that no duplicate emails are added
85
+
* Need to work out how to make sure it checks that no duplicate emails are added
91
86
* Need to make email required field
92
87
* Need to update fields when I know what all of them are
93
-
* Update markdown to include any user creation into a default group so they only have certain priviledges
88
+
* Update markdown to include any user creation into a default group, so they only have certain privileges
0 commit comments