BookClub API

Table of contents

• About
• Quick start (local)
• Configuration
• Running the app
• API overview
• Authentication
• Example requests
• Development
• Tests
• Project structure
• Contributing
• License

About

Bookly (aka BookClub API) is a Django REST Framework backend that powers a social reading/book-exchange platform. It provides user authentication (email + Google OAuth), profile management, book management, genres, and an exchange/book-request flow.

This README was generated from an analysis of the repository code and aims to provide a concise, actionable reference for local development and integration.

Quick start (local)

Prerequisites

• Python 3.8+
• pip
• (Optional) virtualenv

1. Clone the repository

git clone https://github.com/Kiprotich-Code/bookly.git
cd bookly

2. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

If requirements.txt exists in your root, install it. If not, install the common dependencies used by the project:

pip install django djangorestframework djangorestframework-simplejwt django-cors-headers django-allauth dj-rest-auth

4. Apply migrations and create a superuser

python manage.py migrate
python manage.py createsuperuser

5. Run the development server

python manage.py runserver

The API will be available at http://127.0.0.1:8000/ by default.

Configuration

The project stores Django settings in bookclub_api/settings.py. Relevant configuration items:

• AUTH_USER_MODEL = 'accounts.User' — custom user model.
• REST_FRAMEWORK uses TokenAuthentication and SessionAuthentication.
• INSTALLED_APPS includes rest_framework, rest_framework.authtoken, corsheaders, allauth, dj_rest_auth, and the local apps accounts, books, copies.

Environment variables and secrets (e.g., SECRET_KEY, GOOGLE_CLIENT_ID) are expected to be provided in your environment or a .env file (not included).

Running the app

Start the server locally

python manage.py runserver

Access the Django admin at /admin/ after creating a superuser.

API overview

Root mounting points (from bookclub_api/urls.py):

• /admin/ — Django admin
• /books/ — Books and genres API (viewsets)
• /exchange/ — Book exchange / requests (viewsets)
• /accounts/ — Authentication and user profile endpoints

Accounts endpoints (accounts/urls.py):

• POST /accounts/auth/register/ — register (returns token, user_id, email, is_profile_complete)
• POST /accounts/auth/login/ — login (supports type: 'email' or type: 'google'; returns token, user_id, email, is_google, is_profile_complete)
• POST /accounts/auth/logout/ — logout (requires auth)
• POST /accounts/auth/password/reset/ — start password reset flow
• POST /accounts/auth/link-account/ — link Google account to authenticated user
• GET /accounts/user/profile/ — get current authenticated user's profile (returns user object and token)

Books endpoints (router at /books/):

• GET /books/books/ — list books
• POST /books/books/ — create book (authenticated)
• GET /books/books/{id}/ — retrieve book
• PUT/PATCH/DELETE /books/books/{id}/ — update/delete (owner-only)
• GET /books/books/my_books/ — list books belonging to authenticated user
• GET /books/genres/ — list/create genres

Exchange endpoints (router at /exchange/):

• Resource registered at root of the app (see copies.views.BookRequestViewSet) for creating and managing book requests.

Authentication

This project uses Token Authentication by default. When a user registers or logs in, the API returns a token. Include it in requests with the header:

Authorization: Token <token>

Example: fetch current user's profile

GET /accounts/user/profile/
Authorization: Token b42cb92f8851c1aa7320d53fc9fce2318f7dccfe

Response shape (abridged):

{
    "user": {
        "id": 2,
        "username": "James",
        "email": "[email protected]",
        "name": "James",
        "bio": "Test bio!",
        "location": "Nairobi, Kenya",
        "favorite_genres": ["Fiction","Non-Fiction","Science Fiction","Fantasy","Mystery"],
        "profile_picture": null,
        "member_since": "2025-07-05T18:12:57.227096Z",
        "privacy_settings": {"show_email": true, "show_location": true, "show_reading_stats": true},
        "reading_goal": 12,
        "books_read": 0,
        "total_swaps": 0,
        "average_rating": 0
    },
    "token": "b42cb92f8851c1aa7320d53fc9fce2318f7dccfe"
}

Example requests

Register (email):

curl -X POST http://127.0.0.1:8000/accounts/auth/register/ \
    -H "Content-Type: application/json" \
    -d '{"username":"james","email":"[email protected]","password":"securepass"}'

Login (email):

curl -X POST http://127.0.0.1:8000/accounts/auth/login/ \
    -H "Content-Type: application/json" \
    -d '{"type":"email","email":"[email protected]","password":"securepass"}'

Get profile (JS fetch example):

fetch('/accounts/user/profile/', {
    headers: { 'Authorization': `Token ${token}` }
})
    .then(r => r.json())
    .then(console.log)

Development

• Code is organized into Django apps: accounts, books, copies.
• Custom user model lives at accounts.models.User and uses email as the USERNAME_FIELD.
• accounts.serializers.UserProfileSerializer controls the profile representation returned by /accounts/user/profile/.

Recommended development workflow

1. Create a branch
2. Run tests
3. Open a PR with a clear description and linked issue

Tests

Run Django tests with:

python manage.py test

Project structure (top-level)

bookclub_api/            # Django project
accounts/                # custom user, auth, profile
books/                   # book and genre models, viewsets
copies/                  # exchange / request flow
manage.py
db.sqlite3               # local sqlite DB (development)

Contributing

Contributions are welcome. Please open issues for bugs or feature requests and submit pull requests for fixes.

License

This project is licensed under the MIT License — see LICENSE for details.