Wanfadger/AdministrativeAreaService

uganda administrative service # Administrative Area API A read-optimised reference-data service over Uganda's six-level administrative hierarchy: ```text Region › Sub-Region › Local Government › County › Sub-County › Parish ``` It is **read-almost-only** — the hierarchy changes maybe monthly — and is built to be integrated by many services and browsers at once, serving those reads very fast. Spring Boot 3.2.3 on Java 21, with virtual threads enabled. --- ## What it does - **Search and fetch** areas at any level, with dynamic filtering, sorting and paging. Every item carries its **full ancestry** (a parish nests its sub-county → … → region), or just its immediate parent's code when you ask for `?view=flat`. - **Create / update / delete** with parent-scoped duplicate detection and soft delete (an area with children cannot be removed). - **Re-parent** an area, moving its whole sub-hierarchy in one operation. Everything is served behind a **two-tier cache** (see below), so the common read never touches Postgres and the service stays up — degraded to database reads — when Redis is down. --- ## API Base path: `/api/v1/administrative-areas`. All responses are JSON envelopes (`{ data, message, status, … }`); errors are RFC-7807 `application/problem+json`. | Method | Path | Purpose | |---|---|---| | `GET` | `/search` | Page through a level; filter, sort, `?view=flat` | | `GET` | `/{code}` | One area by its code, with full ancestry | | `POST` | `/` | Create an area | | `PUT` | `/{code}` | Update or re-parent | | `DELETE` | `/{code}` | Soft delete (fails if it has children) | ### Searching `GET /search` takes `type` (the level), 1-based `page`, `size` (default 50, max 5000, clamped), `sortBy`, `sortDirection`, `partOf` (a parent's code, to list its children), and `view`. Advanced filters use the grammar `field:OPERATOR=value` as query keys, e.g. `name:CONTAINS=kampala`. Operators: `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `GT`, `GTE`, `LT`, `LTE`, `IN`, `IS_NULL`, `IS_NOT_NULL`. `I …