# API Documentation ## Base URL ``` http://localhost:8080/api ``` All responses are in JSON format. ## Authentication Protected endpoints require a JWT token in the Authorization header: ``` Authorization: Bearer ``` ## Error Responses All error responses follow this format: ```json { "error": "Error message here", "code": "ERROR_CODE" } ``` ## Public Endpoints ### Get All Mangas ```http GET /mangas?page=1&limit=20 ``` **Query Parameters:** - `page` (int) - Page number (default: 1) - `limit` (int) - Items per page (default: 20) - `sort` (string) - Sort by: latest, popular, rating, views - `status` (string) - Filter by status: ongoing, completed, hiatus **Response:** ```json { "data": [ { "id": "uuid", "title": "Manga Title", "description": "Description", "author": "Author Name", "artist": "Artist Name", "cover_image": "url", "rating": 4.5, "views": 1000, "status": "ongoing", "created_at": "2025-01-01T00:00:00Z" } ], "total": 100, "page": 1, "limit": 20 } ``` ### Get Manga Details ```http GET /mangas/:id ``` **Response:** ```json { "id": "uuid", "title": "Manga Title", "description": "Description", "author": "Author Name", "artist": "Artist Name", "cover_image": "url", "rating": 4.5, "views": 1000, "status": "ongoing", "chapters": [ { "id": "uuid", "number": 1, "title": "Chapter 1", "page_count": 25, "created_at": "2025-01-01T00:00:00Z" } ], "tags": ["action", "adventure"], "reviews": [ { "id": "uuid", "user": {"id": "uuid", "username": "user"}, "rating": 5, "comment": "Great manga!", "created_at": "2025-01-01T00:00:00Z" } ] } ``` ### Get Chapter Pages ```http GET /mangas/:id/chapters/:chapterNum/pages ``` **Response:** ```json { "id": "uuid", "number": 1, "title": "Chapter 1", "pages": [ { "id": "uuid", "page_num": 1, "image_url": "https://s3.example.com/..." } ] } ``` ### Search Mangas ```http GET /search?q=query&limit=10 ``` **Query Parameters:** - `q` (string) - Search query (required) - `limit` (int) - Result limit (default: 10) **Response:** ```json { "results": [ { "id": "uuid", "title": "Manga Title", "cover_image": "url", "rating": 4.5 } ] } ``` ## Authentication Endpoints ### Sign Up ```http POST /auth/signup ``` **Request Body:** ```json { "username": "username", "email": "user@example.com", "password": "password" } ``` **Response:** ```json { "token": "jwt_token", "user": { "id": "uuid", "username": "username", "email": "user@example.com" } } ``` ### Sign In ```http POST /auth/signin ``` **Request Body:** ```json { "email": "user@example.com", "password": "password" } ``` **Response:** ```json { "token": "jwt_token", "user": { "id": "uuid", "username": "username", "email": "user@example.com" } } ``` ## Protected Endpoints ### Get User Library ```http GET /library Authorization: Bearer ``` **Response:** ```json { "data": [ { "id": "uuid", "title": "Manga Title", "cover_image": "url", "rating": 4.5 } ] } ``` ### Add to Library ```http POST /library/:id Authorization: Bearer ``` **Response:** ```json { "message": "Added to library" } ``` ### Remove from Library ```http DELETE /library/:id Authorization: Bearer ``` **Response:** ```json { "message": "Removed from library" } ``` ### Upload Manga (Admin Only) ```http POST /upload/manga Authorization: Bearer Content-Type: multipart/form-data ``` **Form Fields:** - `title` (string) - Manga title - `author` (string) - Author name - `artist` (string) - Artist name - `description` (string) - Description - `status` (string) - Status: ongoing, completed, hiatus - `cover` (file) - Cover image **Response:** ```json { "id": "uuid", "title": "Manga Title", "cover_image": "url" } ``` ### Upload Chapter (Admin Only) ```http POST /upload/chapter/:id Authorization: Bearer Content-Type: multipart/form-data ``` **Form Fields:** - `number` (float) - Chapter number - `title` (string) - Chapter title - `pages` (file[]) - Chapter page images **Response:** ```json { "id": "uuid", "number": 1, "title": "Chapter 1", "page_count": 25, "pages": [ { "page_num": 1, "image_url": "url" } ] } ``` ### Create Review ```http POST /reviews/:mangaId Authorization: Bearer ``` **Request Body:** ```json { "rating": 5, "comment": "Great manga!" } ``` **Response:** ```json { "id": "uuid", "rating": 5, "comment": "Great manga!", "created_at": "2025-01-01T00:00:00Z" } ``` ## Status Codes - `200` - Success - `201` - Created - `204` - No Content - `400` - Bad Request - `401` - Unauthorized - `403` - Forbidden - `404` - Not Found - `409` - Conflict - `429` - Too Many Requests - `500` - Internal Server Error ## Rate Limiting Rate limits are applied per IP address: - 100 requests per minute for public endpoints - 1000 requests per minute for authenticated endpoints Rate limit headers: ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 X-RateLimit-Reset: 1234567890 ``` ## Pagination List endpoints support pagination: ```json { "data": [...], "total": 100, "page": 1, "limit": 20, "pages": 5 } ``` ## Example Requests ### Using cURL ```bash # Get all mangas curl http://localhost:8080/api/mangas # Search curl "http://localhost:8080/api/search?q=action" # Sign up curl -X POST http://localhost:8080/api/auth/signup \ -H "Content-Type: application/json" \ -d '{"username":"user","email":"user@example.com","password":"pass"}' # Protected endpoint curl -H "Authorization: Bearer TOKEN" http://localhost:8080/api/library ``` ### Using JavaScript ```javascript // Fetch mangas const response = await fetch('/api/mangas'); const data = await response.json(); // With auth const authResponse = await fetch('/api/library', { headers: { 'Authorization': `Bearer ${token}` } }); ``` ### Using Python ```python import requests # Get mangas response = requests.get('http://localhost:8080/api/mangas') data = response.json() # With auth headers = {'Authorization': f'Bearer {token}'} response = requests.get('http://localhost:8080/api/library', headers=headers) ```