Spaces:

srinu1912066
/

hack-yatra

Paused

App Files Files Community

hack-yatra / docs /API_CONTRACT.md

srinu1912066

Upload folder using huggingface_hub

fa3f945 verified 3 months ago

preview code

Raw History Blame Contribute Delete

7.63 kB

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

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