# Patron API — Install & Usage Guide

Base path: `/api/patron`  
Auth: **HTTP Basic** — `Authorization: Basic base64(username:password)`  
Default: `test` / `test@2024` (override in `.env` with `api.basic.username` / `api.basic.password`)  
Content-Type: `application/json`

Clean URLs (no `index.php`):

| Method | URL |
|--------|-----|
| POST | `/api/patron/upsert` |
| GET | `/api/patron/view` |
| GET | `/api/patron/view?cardnumber=XXX` |
| GET | `/api/patron/overdue` |
| GET | `/api/patron/overdue?cardnumber=XXX` |
| POST | `/api/patron/delete` |

Example: `http://14.139.92.12/dlrl_koha_api/api/patron/view`

---

## Pre-install checklist (do this once)

1. **PHP 8.2+** with extensions: `mysqli`, `mbstring`, `intl`, `json`, `openssl`
2. **Apache** `mod_rewrite` enabled + `AllowOverride All` for this folder
3. Set `app/Config/App.php` → `$baseURL` to your real URL (trailing slash)
4. Set `app/Config/Database.php` → hostname, username, password, database (`koha_library`)
5. Ensure `writable/` is writable by the web server
6. Confirm `public/.htaccess` `RewriteBase` matches your folder name (`/dlrl_koha_api/`)
7. CSRF is **disabled** globally (required for JSON API clients)

### Local XAMPP / WAMP tip

If folder is `htdocs/dlrl_koha_api`:

- `baseURL` = `http://localhost/dlrl_koha_api/`
- `RewriteBase /dlrl_koha_api/`
- Root `.htaccess` already forwards into `public/`

---

## 1. Upsert — `POST /api/patron/upsert`

| Mode | Rule |
|------|------|
| Insert | `cardnumber` not in DB → send full required fields |
| Update | exists → `cardnumber` mandatory; **only sent keys** change |
| Bulk | `"data": [ {...}, {...} ]` |

**Insert mandatory:** `cardnumber`, `surname`, `firstname`, `categorycode`, `userid`, `password`

Optional: address fields, `imagefile` (base64 data URI), attributes `BATCH`, `BG`, `COURSE`, `DEPT`, `DESI`, `LAN`, `MT`

```json
{
  "data": [
    {
      "cardnumber": "DRL001",
      "surname": "Kumar",
      "firstname": "Ravi",
      "categorycode": "ST",
      "userid": "ravi.kumar",
      "password": "Secret@123",
      "email": "ravi@example.com",
      "DESI": "Student",
      "imagefile": "data:image/jpeg;base64,/9j/4AAQ..."
    }
  ]
}
```

Partial update:

```json
{
  "data": [
    { "cardnumber": "DRL001", "email": "new@example.com", "phone": "9998887776" }
  ]
}
```

Each patron runs in a **DB transaction** (borrower + image + attributes).

---

## 2. View — `GET /api/patron/view`

- All patrons: `/api/patron/view`
- One: `/api/patron/view?cardnumber=DRL001`

Password hash is never returned.

---

## 3. Overdue — `GET /api/patron/overdue`

- All: `/api/patron/overdue`
- One: `/api/patron/overdue?cardnumber=DRL001`

Designation = `borrower_attributes` where `code = 'DESI'`.

---

## 4. Delete — `POST /api/patron/delete`

**cardnumber is mandatory** (not optional). Deletes from:

1. `patronimage`
2. `borrower_attributes`
3. `borrowers`

```json
{
  "data": [
    { "cardnumber": "DRL001" },
    { "cardnumber": "DRL002" }
  ]
}
```

Success:

```json
{
  "status": true,
  "message": "All requested patrons deleted successfully.",
  "success_count": 1,
  "failed_count": 0,
  "results": [
    {
      "success": true,
      "index": 0,
      "cardnumber": "DRL001",
      "borrowernumber": 101,
      "message": "Patron and related image/attributes deleted successfully."
    }
  ]
}
```

Not found:

```json
{
  "success": false,
  "cardnumber": "DRL999",
  "message": "Cardnumber \"DRL999\" not found. Nothing deleted."
}
```

If Koha still has issues/fines linked to the patron, MySQL foreign keys may block delete — the API returns that error clearly.

---

## Auth header example

```
Authorization: Basic dGVzdDp0ZXN0QDIwMjQ=
```

(`test:test@2024`)

---

## Quick Postman tests

1. GET `/api/patron/view` + Basic Auth → list or empty message  
2. POST `/api/patron/upsert` with insert JSON → `action: insert`  
3. POST `/api/patron/upsert` with only `cardnumber` + `email` → `action: update`  
4. GET `/api/patron/view?cardnumber=DRL001` → one record  
5. GET `/api/patron/overdue` → overdue list  
6. POST `/api/patron/delete` with cardnumber → deleted  

If URL 404s without `index.php`, check `mod_rewrite`, `AllowOverride`, and `RewriteBase`.