Spaces:
Paused
Paused
File size: 7,630 Bytes
fa3f945 | 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 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 | # GVMC Open Data Platform: Complete API Contract Specification (v1.0)
> **Department**: GVMC - IT Commissioner's Office
> **Event**: HackYatra 2026 | **Track**: Software
> **Binding Contract Version**: 1.0.0
This specification forms the **legally binding REST API contract** between the FastAPI backend, React Web Client (`clients/web`), Expo React Native Mobile Client (`clients/mobile`), and external civic developers.
---
## 1. API Taxonomy & Logical Endpoint Groups
| Module | Base Route | Description |
| :--- | :--- | :--- |
| **System** | `/api/v1` | Health, readiness, liveness, Prometheus metrics & API version info |
| **Authentication** | `/api/v1/auth` | JWT login, registration, DigiLocker SSO, token refresh, logout |
| **Users & Roles** | `/api/v1/users` | User profile management, role assignment, RBAC permission matrix |
| **Datasets Catalog** | `/api/v1/datasets` | Dataset discovery, filtering, metadata, version history, trust scores |
| **Dataset Upload** | `/api/v1/datasets/upload` | Presigned S3/MinIO upload URLs, chunked upload initialization |
| **GIS & Spatial** | `/api/v1/gis` | PostGIS ward polygons, spatial heatmaps, coordinate proximity search |
| **Analytics** | `/api/v1/analytics` | Portal usage totals, ward density indices, department breakdown |
| **Developer Portal** | `/api/v1/developer` | API key generation, revocation, rate limits, quota metrics |
| **Audit & Governance** | `/api/v1/audit` | Immutable audit log trail for compliance and commissioner review |
| **Administration** | `/api/v1/admin` | Dataset approval workflows, user status overrides, platform metrics |
| **Notifications** | `/api/v1/notifications` | In-app alerts, supervisor approval dispatch, email/SMS status |
---
## 2. RBAC Permission Matrix
| Role | Dataset View | Dataset Download | Upload Data | Publish / Approve | Dev API Key | Audit Logs | System Admin |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| `CITIZEN` | Public | Public Files | ❌ | ❌ | ❌ | ❌ | ❌ |
| `STUDENT` | Public | Public Files | ❌ | ❌ | 60 req/min | ❌ | ❌ |
| `RESEARCHER` | All Public + Academic | Restricted Files | ❌ | ❌ | 120 req/min | ❌ | ❌ |
| `STARTUP` | All Public | Commercial Files | ❌ | ❌ | 120 req/min | ❌ | ❌ |
| `FIELD_OFFICER`| All Public | All Public | Draft Upload | ❌ | 60 req/min | ❌ | ❌ |
| `SUPERVISOR` | All Datasets | All Datasets | Upload | Approve / Reject | 120 req/min | View | ❌ |
| `COMMISSIONER` | All Datasets | All Datasets | Full Access | Approve / Archive| Unlimited | Full Access | Full Access |
| `ADMIN` | All Datasets | All Datasets | Full Access | Full Access | Unlimited | Full Access | Full Access |
---
## 3. Unified API Response Schemas
### Standard Success Response Schema (`APIResponse[T]`)
```json
{
"success": true,
"message": "Operation completed successfully",
"data": { ... },
"errors": null
}
```
### Standard Paginated Response Schema (`PaginatedResponse[T]`)
```json
{
"success": true,
"message": "Datasets retrieved successfully",
"data": [ { ... } ],
"pagination": {
"total_items": 148,
"page": 1,
"page_size": 20,
"total_pages": 8,
"has_next": true,
"has_prev": false
},
"errors": null
}
```
### Standard Error Response Schema (`ErrorResponse`)
```json
{
"success": false,
"message": "Authentication failed",
"data": null,
"errors": [
{
"code": "ERR_AUTH_INVALID_CREDENTIALS",
"field": "password",
"message": "Incorrect email or password provided"
}
]
}
```
---
## 4. Endpoints Specifications
### A. Authentication Module (`/api/v1/auth`)
#### `POST /api/v1/auth/login`
- **Purpose**: Authenticate user and issue JWT access & refresh tokens.
- **Auth / RBAC**: Public
- **Request Body**:
```json
{ "email": "researcher@auvizag.edu.in", "password": "SecurePassword123!" }
```
- **Response (200 OK)**:
```json
{
"success": true,
"message": "Authentication successful",
"data": {
"access_token": "eyJhbGciOiJIUzI1Ni...",
"refresh_token": "d9f82a17b01...",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"email": "researcher@auvizag.edu.in",
"full_name": "Dr. A. K. Rao",
"role": "RESEARCHER"
}
}
}
```
#### `POST /api/v1/auth/digilocker`
- **Purpose**: Mock DigiLocker SSO authentication for verified citizen/researcher identity verification.
- **Auth / RBAC**: Public
- **Request Body**:
```json
{ "digilocker_code": "DL_MOCK_AUTH_891234", "state": "GVMC_HACKYATRA" }
```
- **Response (200 OK)**: Standard Token Response with `is_verified: true`.
---
### B. Datasets & Search Module (`/api/v1/datasets`)
#### `GET /api/v1/datasets`
- **Purpose**: Search & filter municipal datasets.
- **Query Parameters**:
- `search` (string): Keyword search in title or description.
- `category` (enum): `WATER_SUPPLY`, `WASTE_MANAGEMENT`, `TRANSPORT`, `PUBLIC_HEALTH`, `URBAN_PLANNING`, `PROPERTY_TAX`, `ENVIRONMENT`.
- `ward_number` (int): Filter by GVMC ward ID (1–98).
- `access_level` (enum): `PUBLIC`, `RESEARCHER_ONLY`, `RESTRICTED`.
- `page` (int, default=1), `page_size` (int, default=20).
- **Response (200 OK)**: `PaginatedResponse[DatasetOut]`.
#### `POST /api/v1/datasets/upload/presign`
- **Purpose**: Request S3/MinIO presigned upload URL for direct file upload.
- **Auth / RBAC**: Required (`FIELD_OFFICER`, `SUPERVISOR`, `COMMISSIONER`, `ADMIN`)
- **Request Body**:
```json
{
"filename": "water_quality_july_2026.csv",
"file_size_bytes": 4200000,
"file_format": "CSV",
"dataset_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}
```
- **Response (200 OK)**:
```json
{
"success": true,
"data": {
"upload_url": "http://localhost:9000/gvmc-datasets/datasets/.../upload?token=...",
"object_key": "datasets/9b1deb4d.../v1.0.0/r1_water_quality.csv",
"expires_in": 3600
}
}
```
---
### C. GIS & PostGIS Spatial Module (`/api/v1/gis`)
#### `GET /api/v1/gis/wards`
- **Purpose**: Get PostGIS polygon boundary geometries for GVMC administrative wards.
- **Response (200 OK)**: Array of `WardBoundaryFeature` containing GeoJSON polygons.
#### `GET /api/v1/gis/heatmaps/{category}`
- **Purpose**: Get backend-calculated spatial density heatmap points.
- **Query Parameters**: `ward_number` (optional int).
- **Response (200 OK)**: Array of `HeatmapPoint` (`latitude`, `longitude`, `weight`, `category`).
---
### D. Developer Portal Module (`/api/v1/developer`)
#### `POST /api/v1/developer/keys`
- **Purpose**: Generate SHA-256 hashed API key for external startup/researcher API access.
- **Auth / RBAC**: Required (`RESEARCHER`, `STARTUP`, `COMMISSIONER`, `ADMIN`)
- **Response (201 Created)**: Returns `api_key_secret` **ONLY ONCE** upon creation.
---
### E. System & Observability Module (`/api/v1`)
#### `GET /api/v1/health`
- **Purpose**: Comprehensive liveness probe checking PostgreSQL, PostGIS, Redis, and MinIO.
#### `GET /api/v1/metrics`
- **Purpose**: Prometheus metrics endpoint (`gvmc_requests_total`, `gvmc_active_workers`).
---
## 5. Performance Standards SLA
| Metric | Target SLA | Strategy |
| :--- | :--- | :--- |
| **API Response Time (P95)** | < 200 ms | Redis caching for catalog queries & spatial heatmaps |
| **Max Payload Size** | 50 MB | Presigned S3/MinIO URLs for dataset file uploads |
| **Database Queries** | < 20 ms | PostGIS GIST spatial indexes & normalized schemas |
| **Compression** | Active | Gzip compression enabled for JSON payloads > 1KB |
|