initial commit

Change-Id: I11e12d8d4c914eabdc30ba4d8be494fd09b617a3

docs/api.md

@@ -0,0 +1,91 @@
+# API Reference
+
+Base URL: `https://test-alex-2.kyndemo.live`
+
+## Items Resource
+
+### GET /api/items
+List all items.
+
+**Response 200**
+```json
+[
+  { "id": 1, "name": "Widget", "description": "A demo widget" }
+]
+```
+
+---
+
+### POST /api/items
+Create a new item.
+
+**Request body**
+```json
+{ "name": "Widget", "description": "A demo widget" }
+```
+
+**Response 200**
+```json
+{ "id": 1, "name": "Widget", "description": "A demo widget" }
+```
+
+---
+
+### GET /api/items/{id}
+Get a single item.
+
+**Path params**: `id` (integer)
+
+**Response 200**
+```json
+{ "id": 1, "name": "Widget", "description": "A demo widget" }
+```
+
+**Response 500** — item not found (throws `NoSuchElementException`)
+
+---
+
+### PUT /api/items/{id}
+Update an existing item.
+
+**Path params**: `id` (integer)
+
+**Request body** (partial update supported)
+```json
+{ "name": "Updated Widget" }
+```
+
+**Response 200**
+```json
+{ "id": 1, "name": "Updated Widget", "description": "A demo widget" }
+```
+
+---
+
+### DELETE /api/items/{id}
+Delete an item.
+
+**Response 200**
+```json
+{ "deleted": 1 }
+```
+
+---
+
+## Health & Observability
+
+### GET /actuator/health
+Spring Boot liveness check.
+
+```json
+{ "status": "UP" }
+```
+
+### GET /actuator/health/liveness
+Kubernetes liveness probe target.
+
+### GET /actuator/health/readiness
+Kubernetes readiness probe target.
+
+### GET /actuator/prometheus
+Prometheus-format metrics for scraping by Prometheus or Grafana Agent.