MedMyDay REST API Documentation

This document summarizes the Django REST API endpoints exposed by the backend for the frontend team. It focuses on URL patterns, methods, authentication / role rules, soft‑delete behaviour, filtering, pagination, file upload flows, and notable custom actions.

Base URL prefix: /api/

Authentication: Bearer JWT in header Authorization: Bearer <token>. User roles: admin, teacher, user (some endpoints/actions restricted).

Pagination: Limit/offset style via DRF Pagination override CustomPagination (page size 48 unless otherwise specified). Standard response shape:

{
  "count": <int>,
  "next": <url|null>,
  "previous": <url|null>,
  "results": [ ... ]
}

Filtering & Search: Any list endpoint supports dynamic query params generated by DynamicFilterSet: - Text fields: accent-insensitive contains search (?name=cardio) - Foreign keys: nested lookup (?specialty_name=cardio) - Boolean / number / date: exact (?ispublished=true) - Array fields: contains

Soft Delete: - Soft-deletable resources expose: DELETE /<resource>/{id}/delete/ and POST /<resource>/{id}/restore/ (method names vary in code but URL pattern consistent). - Admin-only or owner+admin depending on resource (see sections). - GET /<resource>/deleted/ lists only soft deleted entries (role restrictions apply). - Append ?id_deleted=true to normal list/retrieve endpoints to include deleted records in standard responses (still subject to permissions).

File Access: - File path strings (S3 keys) returned along with file_url (short-lived presigned GET URLs). Always consume file_url for downloads/streaming.

Direct Upload Flows: Start + Finish pattern returning presigned POST to S3 then confirmation finish call. - Question file: POST /api/uploads/question_file/start/ → client uploads to S3 → POST /api/uploads/question_file/finish/ - Podcast file: POST /api/uploads/podcast_file/start/ → upload → POST /api/uploads/podcast_file/finish/ - Chapter file: POST /api/uploads/chapter_file/start/ → upload → POST /api/uploads/chapter_file/finish/ - Exercise file: POST /api/uploads/exercise_file/start/ → upload → POST /api/uploads/exercise_file/finish/

Stripe Subscription: - POST /api/subscriptions/create-checkout-session/ → Returns Stripe Checkout session data.

Utility / Meta: - GET /api/ping/ (health check) - GET /api/arborescence/ (hierarchical content outline: blocs → specialties → items) - GET /api/dashboard/ (user-specific dashboard aggregates) - GET /api/ranking/ (leaderboard) - GET /api/trainings/ and GET /api/trainings/filtered/ (training plans views)

Generic ViewSet Conventions

Unless a resource states otherwise, a registered resource <resource> supports: - GET /api/<resource>/ list (excludes heavy nested relationships) - POST /api/<resource>/ create (role restricted on some) - GET /api/<resource>/{id}/ detail (full nested relationships when defined) - PUT /api/<resource>/{id}/ & PATCH /api/<resource>/{id}/ update (role restrictions) - Soft delete & restore endpoints as described (if model is soft-deletable) - GET /api/<resource>/deleted/ (role restrictions) for only deleted

Resources & Custom Actions

Below lists core resources with extra custom actions (only deltas from base behaviour). Paths are relative to /api/.

Users (`/users/`)

Standard CRUD (admin restrictions may apply for listing depending on backend settings). Used for account management.

Blocs (`/blocs/`)

Custom: - DELETE /blocs/{id}/delete/ (admin) - POST /blocs/{id}/restore/ (admin) - GET /blocs/deleted/ (admin)

Specialties (`/specialties/`)

Custom: - GET /specialties/dashboard/ (aggregated specialty metrics) - DELETE /specialties/{id}/delete/ (admin) - POST /specialties/{id}/restore/ (admin) - GET /specialties/deleted/ (admin)

Items (`/items/`)

Custom list filters & actions: - GET /items/my-favorite-items/ (authenticated) → list favorite items for current user - GET /items/specialty/{specialty_id}/ list items for specialty (supports dynamic filters, paginated; returns specialty metadata in extra) - GET /items/{id}/rubrics/ paginated rubrics subset - POST /items/{id}/favorite/ toggle favorite (returns current favorite state) - GET /items/{id}/teachers-notes/ public teacher notes for item - GET /items/{id}/my-personal-notes/ private user notes for item - DELETE /items/{id}/delete/ (admin) deep soft-delete cascades related chapters, files, notes, podcasts, progressions - POST /items/{id}/restore/ (admin) deep restore cascade - GET /items/deleted/ (admin) Note: Standard destroy (DELETE /items/{id}/) is disabled (returns 405).

Chapters (`/chapters/`)

Custom: - DELETE /chapters/{id}/delete/ (admin) - POST /chapters/{id}/restore/ (admin) - GET /chapters/deleted/ (admin)

Rubrics (`/rubrics/`)

Custom: - DELETE /rubrics/{id}/delete/ (admin) - POST /rubrics/{id}/restore/ (admin) - GET /rubrics/deleted/ (admin)

Exercises (`/exercises/`)

Visibility rules: - Admin: all - Teacher: only own - User: only published (is_published=true) Custom actions: - GET /exercises/feedback/ (admin & teacher) exercises with review counts - GET /exercises/{id}/user-progression/ current user's progression (nullable) - GET /exercises/{id}/reviews/ (admin sees user info; teacher limited to own exercise; not for normal users) - DELETE /exercises/{id}/delete/ (admin or owner teacher) deep cascade soft-delete (questions, files, corrections, answers, attempts, progressions, reviews) - POST /exercises/{id}/restore/ (admin or owner teacher) deep restore - GET /exercises/deleted/ (admin full; teacher only own deleted) Destroy disabled.

Exercise Reviews (`/exercise_reviews/`)

Custom: - GET /exercise_reviews/my-exercises-reviews/ (teacher/admin depending) list reviews relevant to user - DELETE /exercise_reviews/{id}/delete/ soft delete (permissions per mixin) - POST /exercise_reviews/{id}/restore/ - GET /exercise_reviews/deleted/

Exams (`/exams/`)

Custom: - GET /exams/upcoming/ - GET /exams/past/ - GET /exams/feedback/ (likely similar to exercises feedback) - GET /exams/{id}/reviews/ - DELETE /exams/{id}/delete/ (admin) - POST /exams/{id}/restore/ (admin) - GET /exams/deleted/ (admin)

Exam Reviews (`/exam_reviews/`)

Custom: - GET /exam_reviews/my-exams-reviews/ - DELETE /exam_reviews/{id}/delete/ - POST /exam_reviews/{id}/restore/ - GET /exam_reviews/deleted/

User Exercise Attempts (`/user_exercise_attempts/`)

Standard CRUD (soft delete actions commented out in code, so currently no custom delete/restore endpoints).

User Exam Attempts (`/user_exam_attempts/`)

Standard CRUD.

User Chapter File Progressions (`/user_chapter_file_progressions/`)

Standard CRUD used to track reading progress per file.

User Progression (implied via `/exercises/{id}/user-progression/`)

Read-only aggregated resource included inside exercise context.

Questions (`/questions/`)

Custom: - DELETE /questions/{id}/delete/ (admin) soft delete - POST /questions/{id}/restore/ (admin) - GET /questions/deleted/ (admin) NOTE: Question list endpoints can be enriched by passing ?include_questions=true when requesting exercises (affects nested serialization in parent views).

Question Files / Corrections / Rubrics

Not directly exposed as top-level endpoints; accessed via parent question / exercise serialization.

Podcasts (`/podcasts/`)

Custom actions (patch / publish toggles etc.) present; key ones: - PATCH /podcasts/{id}/ (via custom empty url_path action) partial update - POST /podcasts/{id}/... actions for publish/unpublish (see backend for exact field semantics) - DELETE /podcasts/{id}/delete/ soft delete - POST /podcasts/{id}/restore/ restore

Recommendations (`/recommendations/`)

Custom patch/post/delete/restore similar to podcasts.

Notes (`/notes/`)

Custom: - GET /notes/my-general-notes/ returns current user's general (non item-bound) notes - PATCH /notes/{id}/partial-update/ partial update helper - DELETE /notes/{id}/delete/ soft delete - POST /notes/{id}/restore/ restore - GET /notes/deleted/ (role logic: admin full, teacher/user own) Additional item-scoped note endpoints live under Items section.

Achievements (`/achievements/`)

Custom: - DELETE /achievements/{id}/delete/ - POST /achievements/{id}/restore/ - GET /achievements/deleted/

Sessions (`/sessions/`)

Likely represent study/practice sessions. Custom: - POST /sessions/exercises_count/ compute how many exercises meet some criteria (payload-defined) - POST /sessions/{id}/remove-exercise/ remove an exercise from session - DELETE /sessions/{id}/delete/ - POST /sessions/{id}/restore/ - GET /sessions/deleted/

Calendar Notes (`/calendar_notes/`)

Large viewset with scheduling utilities. Custom notable actions: - GET /calendar_notes/dashboard/ calendar summary - PATCH /calendar_notes/{id}/ (custom patch action for partial updates) - DELETE /calendar_notes/{id}/delete/ - POST /calendar_notes/{id}/restore/ - GET /calendar_notes/{id}/... additional retrieval helpers (e.g., occurrences) per code (see source for full list)

News (`/news/`)

Image upload integrated in create (admin only). Custom: - DELETE /news/{id}/delete/ - POST /news/{id}/restore/ - GET /news/deleted/

Universities (`/universities/`)

Custom: - GET /universities/cities/ list distinct cities - POST /universities/{id}/ custom post action (e.g., toggle) per code - DELETE /universities/{id}/delete/ - POST /universities/{id}/restore/

Rankings & Gamification

GET /ranking/ returns overall ranking list (points/streaks etc.)

Waiting List (`/waiting_lists/`)

Standard CRUD (used for pre-registration / invitations).

Clerk Invitations (`/clerk-invitations/`)

Manage invitation records (admin oriented). Standard CRUD.

Subscriptions

POST /subscriptions/create-checkout-session/ (Stripe Checkout session creation)

Request / Response Notes

Timestamps: All times are ISO 8601 strings (UTC) unless otherwise specified. Soft delete metadata (present on most models): is_deleted, deleted_at, deleted_by, restored_at, restored_by. Audit metadata: created_at, created_by, updated_at, updated_by. Favoriting: Toggle endpoints return concise state objects (id, related object id, boolean flag). Nested serialization slimmed in list endpoints: heavy arrays (questions, chapters, exercises) omitted unless detail view or explicit flag (?include_questions=true).

Error Patterns

Typical error payload:

{"detail": "Message."}

403 for permission issues, 404 for missing or filtered-out (soft deleted without id_deleted flag) objects, 400 for invalid state transitions (e.g., already deleted/restored).

Role Summary Quick Reference

Resource	Create	Update	Delete/Restore	Deleted Listing
Items	admin	admin	admin	admin
Exercises	admin, teacher (own)	admin (any), teacher (own)	admin or owner teacher	admin (all), teacher (own)
Notes	admin, teacher, user (self)	owner/admin	owner/admin	admin (all), others own
Questions	admin	admin	admin	admin
Chapters / Rubrics / Achievements / Blocs / Specialties	admin	admin	admin	admin
Sessions	(see code; likely admin/teacher)	admin/teacher	admin/teacher	admin/teacher
News	admin	admin	admin	admin

Using `id_deleted` Query Param

Examples: - Include deleted in list: GET /api/items/?id_deleted=true - Retrieve a deleted record (admin) : GET /api/items/123/?id_deleted=1

Favorites Example

Toggle favorite on an item: Request: POST /api/items/42/favorite/ Response:

{
  "id": 88,          // favorite record id
  "item": 42,
  "is_favorite": true
}

Deep Soft Delete / Restore Cascade

For Items and Exercises cascades propagate to related child entities. Frontend should optimistically update UI by removing/restoring dependent collections after success.

Upload Flow Example (Question File)

Start: POST /api/uploads/question_file/start/ → returns { url, fields, key }
Browser performs multipart/form-data POST to S3 using returned fields + file
Finish: POST /api/uploads/question_file/finish/ with body referencing key → backend persists record; response returns finalized resource with file_url.

Common Query Examples

Search specialties by name (accent-insensitive): /api/specialties/?name=cardio Filter items by specialty id: /api/items/?specialties__id=12 Order (all ordering fields allowed): /api/exercises/?ordering=-created_at

Change Log

This initial consolidated documentation file generated (August 19, 2025). Update when endpoints or permissions change.

For any ambiguity (e.g., missing field-level schema), inspect serializer files in website/api/serializers/ or ask backend team.

MedMyDay API Documentation

MedMyDay REST API Documentation

Generic ViewSet Conventions

Resources & Custom Actions

Users (/users/)

Blocs (/blocs/)

Specialties (/specialties/)

Items (/items/)

Chapters (/chapters/)

Rubrics (/rubrics/)

Exercises (/exercises/)

Exercise Reviews (/exercise_reviews/)

Exams (/exams/)

Exam Reviews (/exam_reviews/)

User Exercise Attempts (/user_exercise_attempts/)

User Exam Attempts (/user_exam_attempts/)

User Chapter File Progressions (/user_chapter_file_progressions/)

User Progression (implied via /exercises/{id}/user-progression/)

Questions (/questions/)