# 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 |