docs/API_CONTRACT.md

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])

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... },
  "errors": null
}

Standard Paginated Response Schema (PaginatedResponse[T])

{
  "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)

{
  "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:

  { "email": "researcher@auvizag.edu.in", "password": "SecurePassword123!" }
  

• Response (200 OK):

  {
    "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:

  { "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:

  {
    "filename": "water_quality_july_2026.csv",
    "file_size_bytes": 4200000,
    "file_format": "CSV",
    "dataset_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  }
  

• Response (200 OK):

  {
    "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