Skip to content

Latest commit

 

History

History
881 lines (645 loc) · 14.1 KB

README.md

File metadata and controls

881 lines (645 loc) · 14.1 KB
Raw

QaaS

Application for creation and hosting quizzes

How to run

make all

or

docker-compose --build up -d

Tests

make test

or

docker-compose run --rm qaas pytest /code

Base URL:

Swagger

Admin

MailHog (to check invites and notifications)

Test credentials

  • admin - admin
  • test1 - test
  • test2 - test

API description

All actions of a quiz creator require authentication.

All actions of a quiz participant require either token from invitation (can be passed as a get parameter ?token={token}, or a header "Quiz-token") or authentication

Navigation

[Create Quiz]

[Invite participants]

[Quiz progress]

[Participants and their scores]

[Notify participants about results]

[Quizzes] [Participants] [Invitees] [Questions] [Answers]

[Accept invitation]

[Quizzes for participants]

[Answer a question]

Authentication

Basic, session or JWT

Obtain token

POST http://localhost:8000/api/token/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: application/json

POST /token/

Takes a set of user credentials and returns an access and refresh JSON web token pair to prove the authentication of those credentials.

{
  "username": "string",
  "password": "string"
}

201 Response

{
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTY0ODcwMDA3NiwiaWF0IjoxNjQ4NjEzNjc2LCJqdGkiOiJhYzg2ZWU0MDkxMDc0Y2RlOThlMzhlMjI2YTVjNmExNyIsInVzZXJfaWQiOjJ9.Y_lFEKTUvaC1xbYw3MnmlSVNPtMJpl6vFLbQdqitrcw",
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjQ4NjEzOTc2LCJpYXQiOjE2NDg2MTM2NzYsImp0aSI6IjdkMWQ5YzJhM2QwNTQ5YWZiNGRmMTk0YWQ2YWI2NjYwIiwidXNlcl9pZCI6Mn0.AcTZ9a-iNNnkrb5JN3qLIXP4xcGbSDuQyjDkNgd-rPw"
}

Sign up

users_signup_create

POST http://localhost:8000/api/users/signup/ HTTP/1.1
Host: localhost:8000

POST /users/signup/

{
    "username": "username",
    "password": "qaz",
    "email": "[email protected]"
}

Response

{
    "id": 4,
    "username": "username",
    "email": "[email protected]"
}

Quizmaker

Create Quiz

POST http://localhost:8000/api/quizmaker/quizzes/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: application/json

POST /quizmaker/quizzes/

Body parameter

{
  "title": "Test quiz",
  "questions": [
    {
      "answers": [
        {
          "answer": "Answer 1",
          "correct": true
        },
        {
          "answer": "Answer 2"
        }
      ],
      "question": "Question 1",
      "score": 3
    },
  ],
  "description": "Test description",
  "tags": [
      "tag"
  ]
}

Example response

{
    "id": 1,
    "title": "Test quiz",
    "description": "Some description",
    "questions": [
        {
            "id": 1,
            "answers": [
                {
                    "id": 1,
                    "answer": "Answer 1",
                    "correct": true
                },
                {
                    "id": 2,
                    "answer": "Answer 2",
                    "correct": false
                }
            ],
            "score": 1,
            "question": "Question 1"
        },
    ],
    "tags": [
        "tag"
    ]
}

Read quizzes

GET http://localhost:8000/api/quizmaker/quizzes/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizmaker/quizzes/

GET /quizmaker/quizzes/?created_after=2022-01-03&created_before=2022-05-03&search=something

Example response

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "tags": [
                "tag",
                "another tag"
            ],
            "created_at": "2022-03-29T16:47:28.570660Z",
            "updated_at": "2022-03-29T16:47:28.570709Z",
            "title": "Test quiz",
            "description": "Some description",
            "slug": "test-quiz"
        },
        {
            "id": 2,
            "tags": [
                "another tag"
            ],
            "created_at": "2022-03-29T16:48:04.926682Z",
            "updated_at": "2022-03-29T16:48:04.926725Z",
            "title": "Test quiz 2",
            "description": "Test 2 description",
            "slug": "test-quiz-2"
        }
    ]
}

Read quiz

GET http://localhost:8000/api/quizmaker/quizzes/{id}/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizmaker/quizzes/{id}/

Example response

{
    "id": 1,
    "title": "Test quiz",
    "description": "Some description",
    "questions": [
        {
            "id": 1,
            "answers": [
                {
                    "id": 1,
                    "answer": "Answer 1",
                    "correct": true
                },
                {
                    "id": 2,
                    "answer": "Answer 2",
                    "correct": false
                }
            ],
            "score": 1,
            "question": "Question 1"
        },
    ],
    "tags": [
        "tag",
    ]
}

Quiz - invite participants

POST http://localhost:8000/api/quizmaker/quizzes/{id}/invite/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: application/json

POST /quizmaker/quizzes/{id}/invite/

Body parameter

[
    "[email protected]",
    "[email protected]"
]

Example response

{
    "valid": [
        {
            "[email protected]": "invited"
        },
    ],
    "invalid": [
        {
            "[email protected]": "pending invite"
        },
    ]
}

Quiz - invitees

GET http://localhost:8000/api/quizmaker/quizzes/{id}/invitees/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizmaker/quizzes/{id}/invitees/

Example response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "accepted": false,
            "sent": null,
            "email": "[email protected]"
        },
    ]
}

Quiz - participants

GET http://localhost:8000/api/quizmaker/quizzes/{id}/participants/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizmaker/quizzes/{id}/participants/

GET /quizmaker/quizzes/{id}/participants/?status=completed&[email protected]

Quiz participants and their scores

Example response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "email": "[email protected]",
            "status": "accepted",
            "score_str": "0 out of 7",
            "answered_questions_count": 0,
            "notified": false
        }
    ]
}

Quiz questions

GET http://localhost:8000/api/quizmaker/quizzes/{id}/questions/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizmaker/quizzes/{id}/questions/

GET /quizmaker/quizzes/{id}/questions/?search=question_name

Example response

[
    {
        "id": 1,
        "answers": [
            {
                "id": 1,
                "answer": "Answer 1",
                "correct": true
            },
            {
                "id": 2,
                "answer": "Answer 2",
                "correct": false
            }
        ],
        "score": 1,
        "question": "Question 1"
    }
]

Quiz progress

GET http://localhost:8000/api/quizmaker/quizzes/{id}/progress/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizmaker/quizzes/{id}/progress/

Example response

{
    "invitees_summary": [
        {
            "accepted": false,
            "count": 5
        },
        {
            "accepted": true,
            "count": 1
        }
    ],
    "participants_summary": [
        {
            "status": "accepted",
            "count": 1
        }
    ]
}

Quiz - notify participants

POST http://localhost:8000/api/quizmaker/quizzes/{id}/notify/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: application/json

POST /quizmaker/quizzes/{id}/notify/

Send notifications with results to those who completed the quiz

Example response

200 Response

Questions

GET http://localhost:8000/api/questions/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /questions/

GET /questions/?search=question&quiz={quiz_id}

Example response

{
    "count": 6,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "question": "Question 1",
            "score": 1,
            "quiz": 1
        },
        {
            "id": 2,
            "question": "Question 2",
            "score": 3,
            "quiz": 1
        }
    ]
}

Question

GET http://localhost:8000/api/questions/{id}/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /questions/{id}/

Example response

{
    "id": 1,
    "answers": [
        {
            "id": 1,
            "answer": "Answer 1",
            "correct": true
        },
        {
            "id": 2,
            "answer": "Answer 2",
            "correct": false
        }
    ],
    "score": 1,
    "question": "Question 1"
}

Answers

Code samples

GET http://localhost:8000/api/answers/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /answers/

GET /answers/?search=str&question={question_id}

Example response

{
  "count": 0,
  "next": "http://example.com",
  "previous": "http://example.com",
  "results": [
    {
      "id": 0,
      "answer": "string",
      "correct": true
    }
  ]
}

Quiz - participant perspective

Accept invitation

GET http://localhost:8000/api/accept-invite/{key}/ HTTP/1.1
Host: localhost:8000

GET /accept-invite/{key}/

Example response

{
    "quiz": "http://localhost:8000/api/quizzes/2/?token=6tmst0aizlsggstajinbe9ionqu9uuzocxkj1qbpsad1sok7egsiniignoskik4t"
}

Quizzes

Requires token or authentication

GET http://localhost:8000/api/quizzes/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizzes/?token={token}

Example response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "tags": [
                "tag",
                "another tag"
            ],
            "created_at": "2022-03-29T16:47:28.570660Z",
            "updated_at": "2022-03-29T16:47:28.570709Z",
            "title": "Test quiz",
            "description": "Some description",
            "slug": "test-quiz"
        }
    ]
}

Quiz

Requires token or authentication

GET http://localhost:8000/api/quizzes/{id}/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizzes/{id}/?token={token}

Example response

{
    "id": 1,
    "slug": "test-quiz",
    "title": "Test quiz",
    "description": "Some description",
    "questions": [
        {
            "id": 1,
            "question": "Question 1",
            "answers": [
                {
                    "id": 1,
                    "answer": "Answer 1"
                },
                {
                    "id": 2,
                    "answer": "Answer 2"
                }
            ]
        }
    ],
    "tags": [
        "tag",
    ],
    "link": "http://localhost:8000/api/quizzes/1/"
}

Answering the quiz

POST http://localhost:8000/api/quizzes/{id}/answer/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: application/json

POST /quizzes/{id}/answer/?token={token}

{
  "question": 1,
  "answer": 2
}

Example response

201 Response

{
    "answered_questions_count": 1,
    "total_questions_count": 2,
    "remaining_questions": [
        {
            "id": 2,
            "question": "Question 2",
            "answers": [
                {
                    "id": 3,
                    "answer": "Answer 1"
                },
                {
                    "id": 4,
                    "answer": "Answer 2"
                }
            ]
        }
    ]
}

400 Response

{
    "__all__": [
        "You have already answered this question"
    ]
}

My progress

Requires token or authentication

GET http://localhost:8000/api/quizzes/{id}/my-progress/ HTTP/1.1
Host: localhost:8000
Accept: application/json

GET /quizzes/{id}/my-progress/?token={token}

Example response

{
  "answered_questions_count": 0,
  "total_questions_count": 0,
  "remaining_questions": [
    {
      "id": 0,
      "question": "string",
      "answers": [
        {
          "id": 0,
          "answer": "string"
        }
      ]
    }
  ]
}

Report

GET http://localhost:8000/api/report HTTP/1.1
Host: localhost:8000

GET /report

GET /report?output_format=json

GET /report?output_format=csv