API.md

API Documentation

This document provides a comprehensive overview of the API endpoints and their implementation status. The API is organized into feature modules, each with detailed documentation available in separate files.

📊 Implementation Status

• Required by the task: 34/34 [x]
• Additional features: 18/18 [x]
• Total endpoints: 52/52 [x]

📚 Feature Documentation

• Authentication API - User registration, login, logout, password reset, email verification, and token refresh
• User Management API - User profiles, avatars, administrative functions, and user management
• Post API - Blog posts with advanced filtering, sorting, categories, and comments
• Category API - Post categories for content organization
• Comment API - Nested comments and replies with like/dislike functionality
• Like API - Like and dislike system for posts and comments
• Collections API - User collections for organizing and bookmarking posts

🏗️ Architecture Overview

The API is built with a modular architecture where each feature is self-contained with its own:

• Controller (business logic)
• Service (data operations)
• Model (database schema)
• DTO (data transfer objects)
• Router (endpoint definitions)

🔐 Authentication

Most endpoints require authentication via HTTP-only cookies containing JWT tokens:

• accessToken: Short-lived token (15 minutes)
• refreshToken: Long-lived token for refreshing access

📝 Legend

• — Feature completed
• — Feature not yet implemented
• Optional — Recommended extra feature
• Additional — Feature proposed beyond requirements by me

🚧 TODO Items

• Remove target from validation errors
• Use unsigned int for AUTO_INCREMENT DB columns
• Implement rate limiting
• Implement per day action limits dependent on the user role
• Create config service
• Revise the list of allowed HTML tags for user input sanitization
• Allow to buy "donator" user group. Stripe?
• Extract all hardcoded env (e.g JWT_SECRET)
• Revoke refreshToken by blacklisting untill expires? Should take less space and simplify code.
• Check passwords via haveibeenpwned.com API
• • https://haveibeenpwned.com/API/v3#PwnedPasswords
• Implement AI generated post answer (Gemini?)

🔐 Authentication Endpoints

Method	Endpoint	Description	Status
POST	/api/auth/register	Register new user with email verification	[x]
POST	/api/auth/login	Login user (verified email required)	[x]
POST	/api/auth/logout	Logout authorized user	[x]
POST	/api/auth/password-reset	Send password reset link to email	[x]
POST	/api/auth/password-reset/:confirm_token	Reset password with token	[x]
POST	/api/auth/verify-email/:confirm_token	Verify user email address	[x]
POST	/api/auth/token/refresh	Additional: Refresh access tokens	[x]

👤 User Management Endpoints

Method	Endpoint	Description	Status
GET	/api/users	Get all users with pagination & filtering	[x]
GET	/api/users/:user_id	Get specific user data	[x]
POST	/api/users	Create new user (admin only)	[x]
PATCH	/api/users/avatar	Upload user avatar with processing	[x]
PATCH	/api/users/:user_id	Update user data (owner/admin)	[x]
DELETE	/api/users/:user_id	Soft delete user	[x]
GET	/api/users/:user_id/avatar	Additional: Get user avatar	[x]
POST	/api/users/:user_id/ban	Additional: Ban user	[x]
POST	/api/users/:user_id/unban	Additional: Unban user	[x]
GET	/api/users/me	Additional: Get current user	[x]
GET	/api/users/:user_id/comments	Additional: Get user comments	[x]

Additional Features:

• Pagination with page, limit, sort, order parameters
• Exclude soft deleted users
• Avatar resizing, compression, and WebP conversion
• Animated avatars for donators
• Partial updates supported
• Default avatar fallback

📝 Post Management Endpoints

Method	Endpoint	Description	Status
GET	/api/posts	Get all posts with advanced filtering & pagination	[x]
GET	/api/posts/:post_id	Get specific post data (public)	[x]
POST	/api/posts	Create new post (authenticated)	[x]
PATCH	/api/posts/:post_id	Update post (owner only)	[x]
DELETE	/api/posts/:post_id	Delete post (owner/admin)	[x]
GET	/api/posts/:post_id/comments	Get post comments (public)	[x]
POST	/api/posts/:post_id/comments	Create comment on post	[x]
GET	/api/posts/:post_id/categories	Get post categories	[x]
GET	/api/posts/:post_id/like	Get post likes	[x]
POST	/api/posts/:post_id/like	Like post	[x]
POST	/api/posts/:post_id/dislike	Additional: Dislike post	[x]
DELETE	/api/posts/:post_id/like	Remove like/dislike from post	[x]

Advanced Features:

• Pagination: page, limit parameters
• Sorting: sort (rating, id, created_at, updated_at), order (ASC/DESC)
• Filtering: categories, status, user, from_date, to_date
• Soft Delete: Users can delete own posts, admins can delete any
• Admin Access: Admins can view deleted posts
• Collections: Posts can be added to user collections

Sorting Options:

• By rating (default)
• By creation date
• By update date
• By ID

Filtering Options:

• By categories (comma-separated)
• By date interval
• By status (active/inactive)
• By user ID

Optional Features:

• Collections system for favorites
• Post subscription notifications
• Support for adding images
• • Image upload middleware
• • User content sanitization

🏷️ Category Management Endpoints

Method	Endpoint	Description	Status
GET	/api/categories	Get all categories (public)	[x]
GET	/api/categories/:category_id	Get specific category data (public)	[x]
GET	/api/categories/:category_id/posts	Get posts in category (public)	[x]
POST	/api/categories	Create new category (admin only)	[x]
PATCH	/api/categories/:category_id	Update category (admin only)	[x]
DELETE	/api/categories/:category_id	Delete category (admin only)	[x]

Additional Features:

• Admin authentication required for CUD operations

📚 Collections Management Endpoints

Method	Endpoint	Description	Status
GET	/api/collections	Get user's collections	[x]
POST	/api/collections	Create new collection	[x]
GET	/api/collections/:collection_name	Get collection details	[x]
GET	/api/collections/:collection_name/posts	Get posts in collection	[x]
PATCH	/api/collections/:collection_name	Update collection	[x]
DELETE	/api/collections/:collection_name	Delete collection	[x]
POST	/api/collections/:collection_name/posts	Add post to collection	[x]
DELETE	/api/collections/:collection_name/posts/:post_id	Remove post from collection	[x]

💬 Comment Management Endpoints

Method	Endpoint	Description	Status
GET	/api/comments/:comment_id	Get specific comment data	[x]
POST	/api/comments	Create new comment or reply	[x]
PATCH	/api/comments/:comment_id	Update comment (owner only)	[x]
DELETE	/api/comments/:comment_id	Delete comment (owner only)	[x]
GET	/api/comments/:comment_id/like	Get comment likes	[x]
POST	/api/comments/:comment_id/like	Like comment	[x]
POST	/api/comments/:comment_id/dislike	Additional: Dislike comment	[x]
DELETE	/api/comments/:comment_id/like	Remove like/dislike from comment	[x]

Additional Features:

• Nested comments (replies) support
• Comment threading with parent-child relationships