মনচিত্র প্রজেক্ট গাইড
API ডকুমেন্টেশন
সংস্করণযুক্ত request/response contract, authentication সীমা, validation ও error behavior।
Catalog ও content endpoint
| Route | Request | Response / নিয়ম |
|---|---|---|
| GET /api/books | class, medium, subject, q, cursor | প্রকাশিত বইয়ের summary; filter যাচাই |
| GET /api/books/:bookId | bookId UUID বা slug | বই metadata ও দৃশ্যমান chapter list |
| GET /api/chapters/:chapterId | chapterId | Chapter metadata ও page index |
| GET /api/pages/:pageId | pageId, locale | selectable text node ও licensed asset URL |
শিক্ষার্থী data endpoint
| Route | Access | Validation |
|---|---|---|
| POST /api/annotations | authenticated owner | Zod schema, page scope, kind/color allowlist, length limit |
| GET /api/annotations | authenticated owner | page/book filter auth.uid()-এ সীমাবদ্ধ |
| GET /api/questions/:chapterId | Public active quiz বা authenticated learner | submit-এর আগে answer key নয় |
| POST /api/quiz/submit | authenticated learner | সীমিত answer, এক attempt ID, server score, idempotency |
| GET /api/student/progress | authenticated student বা অনুমোদিত guardian summary | client থেকে arbitrary userId গ্রহণ নয় |
AI, auth ও subscription endpoint
| Route | Request / response | নিরাপত্তা |
|---|---|---|
| POST /api/auth/register | Email, password, nickname, age/consent metadata; confirmation status | rate limit; account enumeration প্রতিরোধ; password log নয় |
| POST /api/ai/explain | selected text, question, locale, chapter reference | server-only Gateway, prompt limit, PII নয়, age-aware output filter |
| POST /api/subscriptions | plan ID ও idempotency key; pending intent ফেরত |
Request ও response উদাহরণ
- ভুল UUID, অজানা question ID, duplicate answer key, non-integer index ও অতিরিক্ত payload প্রত্যাখ্যান করুন।
- স্থায়ী error code ও localized UI message দিন; SQL, provider বা raw auth error প্রকাশ করবেন না।
JSON contract http
POST /api/quiz/submit
Authorization: Bearer <access-token>
Idempotency-Key: 84a0...
Content-Type: application/json
{
"chapterId": "chapter-10-motion",
"answers": { "question-1": 0, "question-2": 2 }
}
200 OK
{
"attemptId": "uuid",
"score": 1,
"total": 2,
"review": [{ "questionId": "question-1", "correct": true }]
}বাস্তবায়ন অবস্থা
- বর্তমান route browser demo; উপরের অধিকাংশ REST contract নির্দিষ্ট, কিন্তু এখনো বাস্তবায়িত নয়।
- authenticated ও unauthorized user দিয়ে deploy/test না করা পর্যন্ত endpoint live বলবেন না।
- external client access-এর আগে pagination, rate limit, versioning ও deprecation নথিভুক্ত করুন।