File size: 2,773 Bytes
9e7b45f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# React API Contract (Session Auth, DB-safe Migration)

This document defines the initial API contract for the Flask template to React migration.
All endpoints below return JSON (except explicit file downloads), use structured status codes, and are safe to consume from React.

## Auth

### POST /api/auth/login/faculty
- Auth: Public
- Request:
```json
{
  "email": "faculty@college.edu",
  "password": "secret"
}
```
- Success 200:
```json
{
  "success": true,
  "user": {
    "email": "faculty@college.edu",
    "name": "Faculty Name",
    "role": "teacher"
  },
  "role": "teacher",
  "redirectPath": "/faculty/dashboard",
  "errors": []
}
```
- Error 400/401/500:
```json
{
  "success": false,
  "message": "Invalid email or password",
  "errors": ["Invalid email or password"]
}
```

### POST /api/auth/login/student
- Auth: Public
- Request:
```json
{
  "roll_no": "22CS101",
  "password": "secret"
}
```
- Success 200:
```json
{
  "success": true,
  "user": {
    "roll_no": "22CS101",
    "name": "Student Name",
    "role": "student"
  },
  "role": "student",
  "redirectPath": "/student/dashboard",
  "errors": []
}
```
- Error 400/401/500: same shape as faculty login

### POST /api/auth/logout
- Auth: Session user
- Success 200:
```json
{
  "success": true,
  "message": "Logged out"
}
```

### GET /api/auth/whoami
- Auth: Optional
- Success 200 (authenticated):
```json
{
  "success": true,
  "authenticated": true,
  "role": "teacher",
  "user": {
    "email": "faculty@college.edu",
    "name": "Faculty Name"
  }
}
```
- Success 200 (anonymous):
```json
{
  "success": true,
  "authenticated": false,
  "role": null,
  "user": null
}
```

## Role Guard Example

### GET /api/admin/ping
- Auth: Session user
- Role: super_admin
- Success 200:
```json
{
  "success": true,
  "message": "admin-ok"
}
```
- Error 401:
```json
{
  "success": false,
  "message": "Unauthenticated",
  "errors": ["Unauthenticated"]
}
```
- Error 403:
```json
{
  "success": false,
  "message": "Forbidden",
  "errors": ["Forbidden"]
}
```

## Existing Routes with JSON Compatibility

The following legacy routes now also return JSON when `Accept: application/json` or `X-Requested-With: XMLHttpRequest` is present:
- `POST /login`
- `POST /student/login`
- `GET|POST /student/logout`
- `GET /multilogin` (status signal)
- `GET /logout`

## Status Code Policy

- `200`: Success
- `400`: Validation error
- `401`: Unauthenticated / bad credentials
- `403`: Unauthorized role
- `404`: Missing resource
- `500`: Internal server error

## Notes

- Session-based auth is intentionally preserved for low-risk migration.
- No schema migration is required for these endpoints.
- File download report endpoints (CSV/PDF) remain file responses and are React-compatible via download links.