API and API Documentation

Acceptance Criteria for API and API Documentation Evaluation

Overview

This document outlines the acceptance criteria and provides examples for API endpoints, expected inputs, outputs, and associated documentation to ensure clear and comprehensive evaluation.

General Acceptance Criteria

1. Functionality:

   • The API must fulfill its intended purpose and perform the required operations without errors.
   • All endpoints should adhere to RESTful principles (if applicable).

2. Error Handling:

   • Clear and descriptive error messages must be returned for all invalid requests.
   • Standardized error codes should be used (such as HTTP status codes).

3. Security:

   • All sensitive data must be transmitted over HTTPS.
   • API keys or Bearer tokens must be used for authentication.

4. Documentation:

   • API documentation must include clear descriptions of each endpoint, required inputs, outputs, and examples.
   • Documentation must be easily accessible and regularly updated.

---

Example API Endpoints

1. Create Quiz Endpoint

URL: /quiz/create/

Method: POST

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <JWT_TOKEN>"
}

Request Body:

{
  "quiz": {
    "title": "Learn Common English Phrases",
    "level": "A1",
    "description": "A quiz designed to help Turkish learners master essential English phrases.",
    "tags": ["phrases", "A1"]
  },
  "questions": [
    {
      "question_text": "What does 'How are you?' mean in Turkish?",
      "choice1": "Merhaba",
      "choice2": "Nasılsınız?",
      "choice3": "Hoşçakal",
      "choice4": "Teşekkürler",
      "correct_choice": 2
    },
    {
      "question_text": "Which word means 'thank you' in English?",
      "choice1": "Lütfen",
      "choice2": "Güle güle",
      "choice3": "Teşekkürler",
      "choice4": "Thank you",
      "correct_choice": 4
    }
  ]
}

Response (Success - 201):

{
  "id": 1,
  "title": "Learn Common English Phrases",
  "level": "A1",
  "description": "A quiz designed to help Turkish learners master essential English phrases.",
  "tags": ["phrases", "A1"],
  "question_count": 2,
  "author": "user123"
}

Response (Error - 400):

{
  "error": "quiz and questions must be provided"
}

2. View Quizzes Endpoint

URL: /feed/quiz/

Method: GET

Headers:

{
  "Authorization": "Bearer <JWT_TOKEN>"
}

Response (Success - 200):

[
  {
    "id": 1,
    "title": "Learn Common English Phrases",
    "level": "A1",
    "description": "A quiz designed to help Turkish learners master essential English phrases.",
    "tags": ["phrases", "A1"],
    "question_count": 2
  },
  {
    "id": 2,
    "title": "Intermediate English Vocabulary",
    "level": "intermediate",
    "description": "A quiz for expanding your English vocabulary.",
    "tags": ["vocabulary", "intermediate"],
    "question_count": 10
  }
]

Response (Error - 401):

{
  "error": "Authentication credentials were not provided."
}

3. Submit Quiz Endpoint

URL: /quiz/submit/

Method: POST

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <JWT_TOKEN>"
}

Request Body:

{
  "quiz_progress_id": 1
}

Response (Success - 200):

{
  "result_url": "/quiz/result/5"
}

Response (Error - 400):

{
  "error": "Please answer all questions"
}

4. Start Quiz Endpoint

URL: /quiz/start/

Method: POST

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <JWT_TOKEN>"
}

Request Body:

{
  "quiz_id": 1
}

Response (Success - 200):

{
  "quiz_progress_id": 3,
  "quiz_title": "Learn Common English Phrases",
  "question_count": 2,
  "questions": [
    {
      "question_number": 1,
      "question": "What does 'How are you?' mean in Turkish?",
      "choices": ["Merhaba", "Nasılsınız?", "Hoşçakal", "Teşekkürler"],
      "previous_answer": null
    },
    {
      "question_number": 2,
      "question": "Which word means 'thank you' in English?",
      "choices": ["Lütfen", "Güle güle", "Teşekkürler", "Thank you"],
      "previous_answer": null
    }
  ]
}

Response (Error - 400):

{
  "error": "Multiple quiz progresses found"
}

Example Related PRs

We can consider the backend team as the main contributors to the following work (Aras, Kaan, Oktay, Halil). Here are some of the PRs regarding API development:

Title	PR	Description
BACKEND-530: Modify docker-compose for database volume and create separate yml for BACKEND-DEV	#533	Improved docker-compose setup by adding separate YML for development.
feat(backend): quiz recommendation	#659	Added functionality for quiz recommendations.
fix(backend): fix quiz feed endpoint data structure	#393	Fixed data structure issues in the quiz feed endpoint.
BACKEND-519: Preliminary quiz endpoints	#573	Introduced preliminary endpoints for quizzes.
feat(backend): improve quiz result endpoint and add quiz review endpoint	#628	Enhanced quiz result endpoint and added support for reviews.
Backend like unlike post	#481	Implemented functionality for liking and unliking posts.

Example Commit

Here's the Milestone 2 Report commit in which we listed the complete documentation of our API up to Milestone 2.

Example Related Issues

Here are some of the issues regarding API development:

Title	Issue	Description
Backend: Get latest quiz review endpoint	#666	The system shall provide an endpoint to fetch the latest quiz review.
Backend: Implement Quiz Recommendation Endpoint	#657	The system shall implement functionality to provide quiz recommendations.
Backend: Implement Quiz Progress Functionality	#520	The system shall enable functionality to track and manage quiz progress.
Create, Delete, Get Posts Endpoints Coding	#518	The system shall support endpoints for creating, deleting, and fetching posts.
Activity Streams Addition to All Views	#517	The system shall integrate activity streams into all relevant views.
[Backend]: Comments Coding	#473	The system shall provide robust functionality for handling comments.
[Backend]: Post Like/Unlike Functionality Coding	#471	The system shall allow users to like and unlike posts.