document API endpoints and usage

README.md

@@ -1,2 +1,6 @@
 # BOS
 BOS (Bugema Operating System) the internet OS! Free, Open Source, Self hostable
+
+## 📘 API Documentation
+
+The BOS API documentation, including endpoints, request/response examples, and authentication details, can be found in the [API Documentation](docs/API.md).

docs/API.md

@@ -0,0 +1,133 @@
+# BOS API Documentation
+
+Welcome to the Bugema Operating System (BOS) API documentation. This API provides a comprehensive backend for managing healthcare operations, patient records, health worker management, and facility operations.
+
+## 🔐 Authentication
+
+The BOS API uses **JSON Web Token (JWT)** for authentication.
+
+### Obtain Token
+**Endpoint:** `/api/v1/auth/token/`  
+**Method:** `POST`  
+**Body:**
+```json
+{
+    "username": "your_username",
+    "password": "your_password"
+}
+```
+**Response (200 OK):**
+```json
+{
+    "access": "eyJ0eXAi...",
+    "refresh": "eyJ0eXAi..."
+}
+```
+
+### Refresh Token
+**Endpoint:** `/api/v1/auth/token/refresh/`  
+**Method:** `POST`  
+**Body:**
+```json
+{
+    "refresh": "eyJ0eXAi..."
+}
+```
+
+> [!NOTE]
+> All subsequent API requests must include the access token in the header:  
+> `Authorization: Bearer <your_access_token>`
+
+---
+
+## 🏥 Core Resources
+
+### Patients
+Manage patient profiles and demographics.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/patients/` | `GET` | List all patients (with filtering) |
+| `/api/v1/patients/` | `POST` | Create a new patient |
+| `/api/v1/patients/{id}/` | `GET` | Retrieve detailed patient info |
+| `/api/v1/patients/{id}/` | `PUT/PATCH` | Update patient info |
+| `/api/v1/patients/search/` | `GET` | Search patients by name, ID, or phone |
+
+**Create Patient Example:**
+`POST /api/v1/patients/`
+```json
+{
+    "first_name": "John",
+    "last_name": "Doe",
+    "gender": "M",
+    "date_of_birth": "1990-01-01",
+    "phone_number": "+256700000000",
+    "location": 1,
+    "registered_facility": 1
+}
+```
+
+---
+
+### Patient Visits
+Track and manage patient visits and consultations.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/visits/` | `GET` | List all visits |
+| `/api/v1/visits/` | `POST` | Schedule/Record a visit |
+| `/api/v1/visits/today/` | `GET` | List visits scheduled for today |
+
+**Create Visit Example:**
+`POST /api/v1/visits/`
+```json
+{
+    "patient": 1,
+    "facility": 1,
+    "visit_type": "OPD",
+    "scheduled_date": "2024-03-23T10:00:00Z",
+    "chief_complaint": "Persistent headache"
+}
+```
+
+---
+
+### Health Records
+Comprehensive medical records management (Clinical Staff only).
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/records/` | `GET` | List health records |
+| `/api/v1/records/` | `POST` | Create a new health record |
+| `/api/v1/records/by-patient/` | `GET` | List records for a specific patient ID |
+
+**List Records by Patient:**
+`GET /api/v1/records/by-patient/?patient_id=PAT-ABC12345`
+
+---
+
+## 🛠️ System Endpoints
+
+### Health Check
+**Endpoint:** `/api/v1/health/`  
+**Method:** `GET`  
+**Description:** Monitor API status and version.
+
+### API Statistics (Admin Only)
+**Endpoint:** `/api/v1/stats/`  
+**Method:** `GET`  
+**Description:** Get general API usage metrics.
+
+---
+
+## ⚠️ Error Handling
+
+The API uses standard HTTP status codes:
+
+- `200 OK`: Request successful.
+- `201 Created`: Resource created successfully.
+- `400 Bad Request`: Invalid input data.
+- `401 Unauthorized`: Missing or invalid authentication token.
+- `403 Forbidden`: Authenticated user lacks sufficient permissions.
+- `404 Not Found`: Resource does not exist.
+- `500 Internal Server Error`: Something went wrong on the server.