Skip to content

API Reference

Jump to bottom
Ilyes BEN BRIK edited this page Jul 22, 2026 · 2 revisions

API Reference

Base URL: http://localhost:8080/api

All protected endpoints require the header:

Authorization: Bearer <jwt_token>

Authentication

Login

POST /api/auth/login

Body:

{"username": "admin", "password": "Admin1234!"}

Response:

{
  "message": "Login successful",
  "token": "eyJ...",
  "user": {"id": "uuid", "username": "admin", "email": "...", "full_name": "...", "role": "admin"}
}

Register

POST /api/auth/register

Body:

{"username": "john", "email": "john@example.com", "password": "MyPass1234!", "full_name": "John Doe"}

Get Profile

GET /api/auth/me

Update Profile

PUT /api/auth/profile

Body (all fields optional):

{"full_name": "New Name", "username": "newuser", "email": "new@example.com"}

Change Password

PUT /api/auth/password

Body:

{"current_password": "OldPass123!", "new_password": "NewPass1234!"}

Books

List Books

GET /api/books?search=&language=&genre=&read_status=&sort_by=created_at&sort_dir=DESC&page=1&per_page=25

Get Book

GET /api/books/{id}

Returns book details + lending history.

Create Book

POST /api/books

Body:

{
  "title": "Book Title",
  "author": "Author Name",
  "genre": "Fiction",
  "language": "arabic",
  "publication_year": 2020,
  "isbn": "9781234567890",
  "edition_house": "Publisher",
  "num_pages": 350,
  "location_room": "Living Room",
  "location_shelf": "Shelf A",
  "shelf_id": "uuid-of-shelf",
  "publisher_id": "uuid-of-publisher",
  "read_status": false,
  "series_name": "",
  "series_position": null,
  "notes": ""
}

Update Book

PUT /api/books/{id}

Body: Same fields as create (all optional).

Delete Book

DELETE /api/books/{id}

Toggle Read Status

POST /api/books/{id}/toggle-read

ISBN Lookup

POST /api/books/isbn-lookup

Body:

{"isbn": "9781234567890"}

Book Scanner

Scan Front Cover

POST /api/scan/cover

Body:

{"image": "data:image/jpeg;base64,..."}

Response:

{
  "data": {
    "parsed": {"title": "Ψ§Ω„Ψ³Ω†Ψ© Ψ§Ω„Ω†Ψ¨ΩˆΩŠΨ©", "author": "Ω…Ψ­Ω…Ψ― Ψ§Ω„ΨΊΨ²Ψ§Ω„ΩŠ"},
    "matches": [],
    "found": false
  }
}

Scan Back Page

POST /api/scan/back

Response includes: isbn, edition_house, publication_year, title, author

Locations

Get Location Tree

GET /api/locations/tree

Returns nested structure: addresses β†’ rooms β†’ shelves.

List Addresses

GET /api/locations

Get Address Details

GET /api/locations/{id}

Returns address + rooms + shelves with book counts.

Create/Update/Delete Address

POST /api/locations
PUT /api/locations/{id}
DELETE /api/locations/{id}

Rooms

GET /api/locations/{address_id}/rooms
POST /api/rooms         (body: {address_id, name, floor, description})
PUT /api/rooms/{id}
DELETE /api/rooms/{id}

Shelves

GET /api/rooms/{room_id}/shelves
POST /api/shelves       (body: {room_id, name, description, capacity})
PUT /api/shelves/{id}
DELETE /api/shelves/{id}

Publishers

List Publishers

GET /api/publishers?search=

CRUD

GET /api/publishers/{id}
POST /api/publishers    (body: {name, name_ar, name_fr, address, city, country, phone, email, website})
PUT /api/publishers/{id}
DELETE /api/publishers/{id}

Writers

List/CRUD

GET /api/writers?search=
GET /api/writers/{id}
POST /api/writers       (body: {name, name_ar, name_fr, nationality, birth_year, death_year, biography})
PUT /api/writers/{id}
DELETE /api/writers/{id}

Genres

GET /api/genres
POST /api/genres        (body: {name, name_ar, name_fr})
PUT /api/genres/{id}
DELETE /api/genres/{id}

Lending

GET /api/lending?status=all|active|overdue|returned
POST /api/lending       (body: {book_id, borrower_name, borrower_contact, due_date, notes})
PUT /api/lending/{id}   (body: {due_date, notes, borrower_contact})
POST /api/lending/{id}/return
DELETE /api/lending/{id}
GET /api/lending/overdue

Reports

GET /api/reports/summary
GET /api/reports/by-genre
GET /api/reports/by-author?limit=20
GET /api/reports/by-year
GET /api/reports/by-location
GET /api/reports/lending-history?from_date=&to_date=
GET /api/reports/export/csv     (downloads file)
GET /api/reports/export/pdf     (downloads file)

Users (Admin)

GET /api/users
GET /api/users/{id}
PUT /api/users/{id}     (body: {full_name, email, role, is_active})
DELETE /api/users/{id}

Backup (Admin)

POST /api/backup/create
GET  /api/backup/list
GET  /api/backup/download/{filename}
DELETE /api/backup/{filename}

E-Book Plugin

Plugin Control (Admin only)

GET  /api/ebook-plugin/status
POST /api/ebook-plugin/enable
POST /api/ebook-plugin/disable

All /api/ebooks/* endpoints return 403 if the plugin is disabled.

List E-Books

GET /api/ebooks?search=&format=pdf|epub|mobi&page=1&per_page=24

Response includes publisher_name (joined from publishers table).

Get E-Book

GET /api/ebooks/{id}

Upload E-Book

POST /api/ebooks/upload

Body: multipart/form-data

Field Type Required Description
file File βœ… PDF, EPUB, or MOBI (max 100 MB)
title string Override auto-detected title
author string Override auto-detected author
publisher_id UUID Link to an existing publisher
total_pages integer Manual page count

Response:

{
  "message": "E-book uploaded successfully.",
  "data": { ...ebook object... },
  "metadata_complete": true
}

Update E-Book Metadata

PUT /api/ebooks/{id}

Body (all optional):

{
  "title": "New Title",
  "author": "Author Name",
  "publisher_id": "uuid",
  "total_pages": 350,
  "notes": ""
}

Delete E-Book

DELETE /api/ebooks/{id}

Also deletes the physical file and cover from storage.

Update Reading Progress

POST /api/ebooks/{id}/progress

Body:

{"current_page": 42}

Response:

{
  "data": {
    "id": "uuid",
    "current_page": 42,
    "total_pages": 350,
    "read_percentage": 12.0
  }
}

Open / Stream File

GET /api/ebooks/{id}/open
  • PDF: Content-Disposition: inline (browser opens PDF viewer)
  • EPUB/MOBI: Content-Disposition: attachment (browser downloads)

Serve Cover Image

GET /api/ebooks/{id}/cover

Returns the cover image binary (image/jpeg or image/png).
Returns { "cover_url": null, "source": "default" } if no cover has been set.

Upload Custom Cover

POST /api/ebooks/{id}/cover

Body: multipart/form-data with field cover (JPEG, PNG, or WEBP, max 5 MB).

Re-extract Cover from File

POST /api/ebooks/{id}/reextract-cover

Re-renders the first page of the PDF or reads the EPUB manifest cover.

Fetch Cover from Open Library

POST /api/ebooks/{id}/refresh-cover

Body (optional β€” defaults to stored title/author):

{"title": "Search title", "author": "Author name"}

Error Responses

{"error": "Error message here."}        // Single error (with HTTP status code)
{"errors": ["Field 'x' is required."]}  // Validation errors (422)

HTTP Status Codes

Code Meaning
200 Success
201 Created
401 Unauthorized (invalid/expired token)
403 Forbidden (insufficient role)
404 Not found
409 Conflict (duplicate)
422 Validation error
429 Rate limited
500 Server error

πŸ“š Bookoholik Wiki

Getting Started

Features

User Guide

Administration

Developer

Release Notes

Clone this wiki locally