Skip to content

api-documentation.md

Latest commit

 

History

History
643 lines (530 loc) · 13.6 KB

api-documentation.md

File metadata and controls

643 lines (530 loc) · 13.6 KB

API Documentation

College Library Management System

Overview

This document provides comprehensive API documentation for the College Library Management System, including Firestore database schema, REST API endpoints, Telegram bot commands, and data models.

Table of Contents

  1. Database Schema
  2. REST API Endpoints
  3. Telegram Bot Commands
  4. Data Models
  5. Authentication
  6. Error Handling

Database Schema

Firestore Collections Structure

library-management/
├── users/                          # User profiles and authentication
├── books/                          # Book catalog and metadata
├── requests/                       # Book borrowing requests
├── notifications/                  # System notifications
├── settings/                       # System configuration
├── analytics/                      # Usage analytics and reports
└── sessions/                       # Active user sessions

Users Collection

Collection Path: /users/{userId}

interface User {
  id: string;                       // Firebase Auth UID
  email?: string;                   // Email (for staff)
  telegramId?: string;              // Telegram user ID (for students)
  profile: {
    firstName: string;
    lastName: string;
    studentId?: string;             // Student ID number
    employeeId?: string;            // Staff employee ID
    department: string;
    phone?: string;
    avatar?: string;                // Profile picture URL
  };
  role: 'student' | 'librarian' | 'admin';
  status: 'active' | 'suspended' | 'inactive';
  preferences: {
    notifications: {
      dueDateReminders: boolean;
      requestUpdates: boolean;
      announcements: boolean;
    };
    language: string;               // Default: 'en'
  };
  statistics: {
    totalRequests: number;
    approvedRequests: number;
    currentLoans: number;
    overdueBooks: number;
    totalFines: number;
  };
  createdAt: Timestamp;
  updatedAt: Timestamp;
  lastLoginAt?: Timestamp;
}

Books Collection

Collection Path: /books/{bookId}

interface Book {
  id: string;                       // Auto-generated book ID
  isbn: string;                     // ISBN-10 or ISBN-13
  title: string;
  subtitle?: string;
  authors: string[];                // Array of author names
  publisher: string;
  publishedDate: string;            // ISO date string
  edition?: string;
  language: string;                 // Default: 'en'
  pages?: number;
  categories: string[];             // Subject categories
  description?: string;
  coverImage?: string;              // Cover image URL
  availability: {
    totalCopies: number;
    availableCopies: number;
    reservedCopies: number;
    status: 'available' | 'limited' | 'unavailable';
  };
  location: {
    section: string;                // Library section
    shelf: string;                  // Shelf identifier
    callNumber: string;             // Library call number
  };
  metadata: {
    addedBy: string;                // User ID who added the book
    addedAt: Timestamp;
    updatedBy?: string;
    updatedAt?: Timestamp;
  };
  statistics: {
    totalRequests: number;
    currentLoans: number;
    averageRating?: number;
    reviewCount: number;
  };
}

Requests Collection

Collection Path: /requests/{requestId}

interface BookRequest {
  id: string;                       // Auto-generated request ID
  userId: string;                   // Requesting user ID
  bookId: string;                   // Requested book ID
  status: 'pending' | 'approved' | 'rejected' | 'borrowed' | 'returned' | 'overdue';
  type: 'borrow' | 'reserve';
  requestDate: Timestamp;
  approvedDate?: Timestamp;
  borrowDate?: Timestamp;
  dueDate?: Timestamp;
  returnDate?: Timestamp;
  approvedBy?: string;              // Librarian user ID
  notes?: string;                   // Additional notes
  qrCode?: string;                  // QR code for validation
  fine?: {
    amount: number;
    reason: string;
    paidAt?: Timestamp;
    paidAmount?: number;
  };
  timeline: RequestTimelineEntry[]; // Status change history
}

interface RequestTimelineEntry {
  status: string;
  timestamp: Timestamp;
  userId: string;                   // User who made the change
  notes?: string;
}

Notifications Collection

Collection Path: /notifications/{notificationId}

interface Notification {
  id: string;
  userId: string;                   // Target user ID
  type: 'due_reminder' | 'request_update' | 'announcement' | 'fine_notice';
  title: string;
  message: string;
  data?: Record<string, any>;       // Additional notification data
  status: 'pending' | 'sent' | 'failed';
  channels: ('telegram' | 'email' | 'web')[];
  scheduledAt?: Timestamp;          // For scheduled notifications
  sentAt?: Timestamp;
  readAt?: Timestamp;
  createdAt: Timestamp;
}

REST API Endpoints

Base URL

  • Development: https://us-central1-library-dev.cloudfunctions.net/api
  • Production: https://us-central1-library-prod.cloudfunctions.net/api

Authentication Endpoints

POST /auth/login

Login with email and password (staff only)

Request Body:

{
  "email": "librarian@college.edu",
  "password": "securePassword123"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user123",
      "email": "librarian@college.edu",
      "role": "librarian",
      "profile": { ... }
    },
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

POST /auth/telegram

Authenticate Telegram user

Request Body:

{
  "telegramId": "123456789",
  "firstName": "John",
  "lastName": "Doe",
  "username": "johndoe"
}

User Management Endpoints

GET /users

Get all users (admin/librarian only)

Query Parameters:

  • role: Filter by user role
  • status: Filter by user status
  • limit: Number of results (default: 50)
  • offset: Pagination offset

Response:

{
  "success": true,
  "data": {
    "users": [...],
    "total": 150,
    "hasMore": true
  }
}

GET /users/{userId}

Get user by ID

PUT /users/{userId}

Update user profile

DELETE /users/{userId}

Deactivate user (admin only)

Book Management Endpoints

GET /books

Search and list books

Query Parameters:

  • q: Search query (title, author, ISBN)
  • category: Filter by category
  • availability: Filter by availability status
  • limit: Number of results (default: 20)
  • offset: Pagination offset

Response:

{
  "success": true,
  "data": {
    "books": [
      {
        "id": "book123",
        "title": "Introduction to Computer Science",
        "authors": ["John Smith", "Jane Doe"],
        "isbn": "978-0123456789",
        "availability": {
          "totalCopies": 5,
          "availableCopies": 3,
          "status": "available"
        }
      }
    ],
    "total": 1250,
    "hasMore": true
  }
}

POST /books

Add new book (librarian/admin only)

Request Body:

{
  "isbn": "978-0123456789",
  "title": "Introduction to Computer Science",
  "authors": ["John Smith", "Jane Doe"],
  "publisher": "Tech Publications",
  "publishedDate": "2023-01-15",
  "categories": ["Computer Science", "Programming"],
  "totalCopies": 5,
  "location": {
    "section": "CS",
    "shelf": "A1",
    "callNumber": "004.1 SMI"
  }
}

PUT /books/{bookId}

Update book information

DELETE /books/{bookId}

Remove book from catalog

Request Management Endpoints

GET /requests

Get book requests

Query Parameters:

  • userId: Filter by user ID
  • status: Filter by request status
  • bookId: Filter by book ID
  • limit: Number of results
  • offset: Pagination offset

POST /requests

Submit book request

Request Body:

{
  "bookId": "book123",
  "type": "borrow",
  "notes": "Needed for research project"
}

PUT /requests/{requestId}/approve

Approve book request (librarian/admin only)

Request Body:

{
  "dueDate": "2024-02-15T00:00:00Z",
  "notes": "Approved for 2 weeks"
}

PUT /requests/{requestId}/reject

Reject book request

PUT /requests/{requestId}/return

Mark book as returned

Analytics Endpoints

GET /analytics/dashboard

Get dashboard analytics (librarian/admin only)

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalBooks": 5000,
      "totalUsers": 1200,
      "activeRequests": 45,
      "overdueBooks": 12
    },
    "trends": {
      "dailyRequests": [...],
      "popularBooks": [...],
      "userActivity": [...]
    }
  }
}

Telegram Bot Commands

Student Commands

/start

Initialize bot and register user

  • Usage: /start
  • Response: Welcome message and registration prompt

/search

Search for books

  • Usage: /search <query>
  • Example: /search python programming
  • Response: List of matching books with availability

/request

Request a book

  • Usage: /request <book_id>
  • Example: /request book123
  • Response: Confirmation of request submission

/status

Check request status

  • Usage: /status
  • Response: List of current requests with status

/history

View borrowing history

  • Usage: /history
  • Response: Past borrowing records

/profile

View/edit user profile

  • Usage: /profile
  • Response: Current profile information with edit options

/help

Show available commands

  • Usage: /help
  • Response: List of all available commands

Admin Commands

/admin_stats

View system statistics (admin only)

  • Usage: /admin_stats
  • Response: System usage statistics

/admin_broadcast

Send announcement to all users (admin only)

  • Usage: /admin_broadcast <message>
  • Response: Confirmation of broadcast

Data Models

API Response Format

All API responses follow this standard format:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  meta?: {
    timestamp: string;
    requestId: string;
    version: string;
  };
}

Pagination

interface PaginatedResponse<T> {
  items: T[];
  total: number;
  limit: number;
  offset: number;
  hasMore: boolean;
}

Search Results

interface SearchResult<T> {
  items: T[];
  total: number;
  query: string;
  filters: Record<string, any>;
  suggestions?: string[];
}

Authentication

JWT Token Structure

interface JWTPayload {
  sub: string;                      // User ID
  email?: string;                   // User email
  role: string;                     // User role
  iat: number;                      // Issued at
  exp: number;                      // Expires at
  aud: string;                      // Audience
  iss: string;                      // Issuer
}

Authorization Headers

All authenticated requests must include:

Authorization: Bearer <jwt_token>

Role-based Access

  • Student: Can view books, submit requests, view own data
  • Librarian: Student permissions + manage requests, view all users
  • Admin: All permissions + system configuration, user management

Error Handling

HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 422 - Validation Error
  • 429 - Rate Limited
  • 500 - Internal Server Error

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}

Common Error Codes

  • INVALID_TOKEN - Authentication token is invalid
  • INSUFFICIENT_PERMISSIONS - User lacks required permissions
  • RESOURCE_NOT_FOUND - Requested resource doesn't exist
  • VALIDATION_ERROR - Input validation failed
  • RATE_LIMITED - Too many requests
  • BOOK_UNAVAILABLE - Book is not available for borrowing
  • REQUEST_ALREADY_EXISTS - User already has pending request for book

Rate Limiting

API Endpoints

  • General: 100 requests per minute per user
  • Search: 30 requests per minute per user
  • Authentication: 10 requests per minute per IP

Telegram Bot

  • Commands: 20 commands per minute per user
  • Messages: 50 messages per minute per user

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Webhooks

Telegram Bot Webhook

Endpoint: https://your-domain.com/webhook/telegram Method: POST Content-Type: application/json

Request Validation

All webhook requests are validated using:

  • HMAC-SHA256 signature verification
  • Timestamp validation (within 5 minutes)
  • IP whitelist verification

SDK Examples

JavaScript/TypeScript

import { LibraryAPI } from '@library/sdk';

const api = new LibraryAPI({
  baseURL: 'https://api.library.edu',
  apiKey: 'your-api-key'
});

// Search books
const books = await api.books.search({
  query: 'javascript',
  limit: 10
});

// Submit request
const request = await api.requests.create({
  bookId: 'book123',
  type: 'borrow'
});

Python

from library_sdk import LibraryClient

client = LibraryClient(
    base_url='https://api.library.edu',
    api_key='your-api-key'
)

# Search books
books = client.books.search(
    query='python',
    limit=10
)

# Submit request
request = client.requests.create(
    book_id='book123',
    type='borrow'
)

Document Version: 1.0 Last Updated: [Current Date] Prepared By: API Development Team Reviewed By: [To be filled]