Patron API Documentation — DLRL Koha

Base URL: http://14.139.92.12/dlrl_koha_api/
Auth: HTTP Basic — username test / password test@2024
Header: Authorization: Basic dGVzdDp0ZXN0QDIwMjQ=
Content-Type: application/json
Clean URLs: no index.php required

Method	Endpoint
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

1. Upsert Patron — POST /api/patron/upsert

Rules

Mode	Rule
Insert	If cardnumber does not exist → send full patron JSON
Update	If exists → cardnumber mandatory; send only keys to change
Multiple	Put one or many objects inside "data": [ ... ]

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

Optional borrower fields: title, othernames, initials, streetnumber, address, address2, city, state, zipcode, country, email, phone, dateofbirth, dateenrolled, dateexpiry, sex, branchcode (default DLRL)

Image: imagefile (base64 data URI) + optional mimetype (e.g. image/png)

Borrower attribute codes

Code	Example
DESIG	SCIENTIS-E
DIV	MV-3
RT	No

Note: JSON must be valid. Do not leave a trailing comma after the last property.

Full insert example

{
  "data": [
    {
      "cardnumber": "CQR40",
      "surname": "VVVV",
      "firstname": "K",
      "title": "CQR40",
      "othernames": "VK",
      "initials": "K",
      "streetnumber": "123",
      "address": "Coimbatore",
      "address2": "",
      "city": "Mettupalayam",
      "state": "TamilNadu",
      "zipcode": "641301",
      "country": "India",
      "email": "vk123@gmail.com",
      "phone": "1234567890",
      "dateofbirth": "2000-01-01",
      "categorycode": "2CQR",
      "dateenrolled": "2024-09-19",
      "dateexpiry": "2040-09-19",
      "sex": "M",
      "userid": "CQR40",
      "password": "CQR40",
      "imagefile": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/...",
      "mimetype": "image/png",
      "DESIG": "SCIENTIS-E",
      "DIV": "MV-3",
      "RT": "No"
    }
  ]
}

Partial update example

{
  "data": [
    {
      "cardnumber": "CQR40",
      "email": "new.email@gmail.com",
      "phone": "9876543210",
      "DESIG": "SCIENTIST"
    }
  ]
}

Success response

{
  "status": true,
  "message": "All patrons processed successfully.",
  "success_count": 1,
  "failed_count": 0,
  "results": [
    {
      "success": true,
      "index": 0,
      "cardnumber": "CQR40",
      "borrowernumber": 101,
      "action": "insert",
      "message": "Patron inserted successfully."
    }
  ]
}

action is insert or update. Each patron is saved in a DB transaction (borrowers + patronimage + borrower_attributes).

2. View Patron — GET /api/patron/view

All patrons: /api/patron/view
One patron: /api/patron/view?cardnumber=CQR40

Returns borrower fields (password excluded), imagefile (base64), mimetype, flat attributes DESIG / DIV / RT, and codes_attributes list.

3. Overdue — GET /api/patron/overdue

All: /api/patron/overdue
One: /api/patron/overdue?cardnumber=CQR40

Designation = borrower_attributes where code = DESIG.

Columns: S_No, ID_No, Name, Designation, Acc_No, Title, Author, Issue_Date, Due_Date, Overdue_Days

4. Delete Patron — POST /api/patron/delete

cardnumber is mandatory. Deletes in order: patronimage → borrower_attributes → borrowers.

{
  "data": [
    { "cardnumber": "CQR40" }
  ]
}

Common error messages

Message	Cause
Authorization header is required...	Missing Basic Auth
Invalid username or password.	Bad credentials
Invalid JSON body: ...	Malformed JSON (check trailing commas)
cardnumber is mandatory...	Missing cardnumber
Insert failed. Missing mandatory field(s): ...	Incomplete insert
imagefile is not valid base64 data.	Bad image payload
Cardnumber "X" not found. Nothing deleted.	Delete target missing
Database connection failed...	Wrong DB config

Server checklist

PHP 8.2+ (mysqli, mbstring, intl, json)
Apache mod_rewrite + AllowOverride All
App.php → baseURL and indexPage = ''
Database.php → Koha DB credentials
writable/ folder writable
public/.htaccess → RewriteBase /dlrl_koha_api/