# REST API v1 Architecture and Interface Documentation
## Kampong Speu Provincial Demographic Management System (KSP-DMS)

**Document Code:** KSP-DMS-DOC-API-01  
**Protocol:** HTTPS / RESTful JSON  
**Authentication:** Laravel Sanctum Bearer Tokens  
**Base URL:** `/api/v1`  
**Version:** 1.0 (Draft Proposal)  

---

## 1. API Architecture Principles

1. **Stateless Authentication:** Mobile clients and integration endpoints authenticate via Bearer tokens generated via `/api/v1/login`.
2. **Standardized Response Envelope:** Every JSON response conforms to a predictable, consistent envelope:
   ```json
   {
     "success": true,
     "message": "Data retrieved successfully",
     "data": {},
     "meta": {
       "timestamp": "2026-11-20T08:00:00Z",
       "version": "1.0"
     }
   }
   ```
3. **Geographic Confinement:** The authenticated user's geographic scope is automatically enforced on all API resource queries.
4. **Offline Synchronization Design:** Submissions from field devices include client-generated UUIDs (`mutation_id`) ensuring idempotent execution and zero duplicate record insertion during network retries.

---

## 2. API Endpoints Specification

### 2.1 Authentication & Profile
- `POST /api/v1/login`: Accepts `username` and `password`. Returns Sanctum bearer token and user profile including geographic scope.
- `POST /api/v1/logout`: Revokes active bearer token.
- `GET /api/v1/user/profile`: Returns authenticated user identity, role, and assigned geographic division.

### 2.2 Geographic Hierarchy
- `GET /api/v1/areas/districts`: Returns list of districts in Kampong Speu.
- `GET /api/v1/areas/communes?district_id={id}`: Returns communes within a district.
- `GET /api/v1/areas/villages?commune_id={id}`: Returns villages within a commune.

### 2.3 Household Registry
- `GET /api/v1/households?village_id={id}&page={n}`: Paginated list of households within user's scope.
- `POST /api/v1/households`: Drafts a new household record.
- `GET /api/v1/households/{id}`: Detailed view of household and active member roster.
- `PUT /api/v1/households/{id}`: Updates draft household details.

### 2.4 Person Registry
- `GET /api/v1/persons?household_id={id}`: List of individuals registered in a household.
- `POST /api/v1/persons`: Registers an individual and associates them with a household.
- `GET /api/v1/persons/{id}`: Full demographic profile of an individual.

### 2.5 Vital Events
- `POST /api/v1/events/birth`: Registers a birth notice.
- `POST /api/v1/events/death`: Registers a death notice.
- `POST /api/v1/events/migration`: Registers an inbound or outbound migration.

### 2.6 Submissions & Approvals
- `GET /api/v1/submissions`: Lists pending submissions within reviewer's scope.
- `POST /api/v1/submissions`: Submits a batch of drafted changes for review.
- `POST /api/v1/submissions/{id}/verify`: Commune reviewer certification.
- `POST /api/v1/submissions/{id}/approve`: District reviewer final approval.
- `POST /api/v1/submissions/{id}/reject`: Reviewer rejection with mandatory justification.

### 2.7 Spatial & Aggregated Statistics
- `GET /api/v1/reports/demographic-summary`: Aggregated population, gender ratio, and age cohorts.
- `GET /api/v1/maps/choropleth`: Returns GeoJSON polygons enriched with demographic metrics for GIS display.

---

## 3. Error Codes & Exception Handling

| HTTP Code | Error Meaning | Example Response |
| :--- | :--- | :--- |
| **401 Unauthorized** | Missing or expired token | `{"success": false, "message": "Unauthenticated"}` |
| **403 Forbidden** | Attempted access outside assigned geographic scope | `{"success": false, "message": "Geographic access violation"}` |
| **422 Unprocessable**| Validation failure | `{"success": false, "errors": {"dob": ["The dob field is required."]}}` |
| **429 Too Many Req** | Rate limit exceeded | `{"success": false, "message": "Rate limit exceeded. Try again in 60s."}` |
