# Django FaceLook Media API Documentation ## Table of Contents - [Authentication](#authentication) - [User Management](#user-management) - [Post Management](#post-management) - [Category Management](#category-management) - [Comment Management](#comment-management) - [Like Management](#like-management) - [Follow Management](#follow-management) - [Image Management](#image-management) - [Notification Management](#notification-management) - [Error Responses](#error-responses) --- ## Base URL http://localhost:8000/api/v1 --- ## Authentication ### Register New User URL: POST /auth/register/ Headers: ```json { "Content-Type": "application/json" } ``` Body: ```json { "username": "john_doe", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "password": "securepassword123", "password_confirm": "securepassword123" } ``` Expected Response (201 Created): ```json { "user": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "bio": "", "avatar": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" }, "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` --- ### Login User URL: POST /auth/login/ Headers: ```json { "Content-Type": "application/json" } ``` Body: ```json { "username": "john_doe", "password": "securepassword123" } ``` Expected Response (200 OK): ```json { "user": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "bio": "", "avatar": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" }, "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` --- ### Logout User URL: POST /auth/logout/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "message": "Logged out successfully" } ``` --- ### Get Current User Profile URL: GET /auth/profile/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "bio": "", "avatar": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ``` --- ### Update User Profile URL: PUT /auth/profile/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } Body: ```json { "bio": "Software developer passionate about Django", "first_name": "John Updated" } Expected Response (200 OK): ```json { "id": 1, "username": "john_doe", "first_name": "John Updated", "last_name": "Doe", "email": "john@example.com", "bio": "Software developer passionate about Django", "avatar": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T11:00:00Z" } --- ### Delete User Account URL: DELETE /auth/delete/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } Expected Response (204 No Content): (no content) --- ### View User Profile URL: GET /auth/profile/{user_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "bio": "Designer and artist", "avatar": null, "created_at": "2024-01-15T11:00:00Z", "updated_at": "2024-01-15T11:00:00Z", "is_following": false, "followers_count": 5, "following_count": 12 } ``` --- ### Follow User URL: POST /auth/follow/{user_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (201 Created): ```json { "message": "User followed successfully" } ``` --- ### Unfollow User URL: DELETE /auth/unfollow/{user_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "message": "User unfollowed successfully" } ``` --- ## Post Management ### Create Post URL: POST /posts/create/ Headers: ```json { "Content-Type": "multipart/form-data", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body (multipart/form-data): ```json content: "This is my first post on this social media platform!" category: 1 images: [file1.jpg, file2.jpg, file3.jpg] ``` Expected Response (201 Created): ```json { "id": 1, "content": "This is my first post on this social media platform!", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T12:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "images": [ { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T12:00:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } }, { "id": 2, "image": "http://localhost:8000/media/images/post_image_20240115_143001.jpg", "created_at": "2024-01-15T12:00:01Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } }, { "id": 3, "image": "http://localhost:8000/media/images/post_image_20240115_143002.jpg", "created_at": "2024-01-15T12:00:02Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } } ], "likes_count": 0, "comments_count": 0, "is_liked": false } ``` --- ### Add Images to Existing Post URL: POST /images/post/{post_id}/add/ Headers: ```json { "Content-Type": "multipart/form-data", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body (multipart/form-data): ```json images: [file1.jpg, file2.jpg] ``` Expected Response (201 Created): ```json [ { "id": 4, "image": "http://localhost:8000/media/images/post_image_20240115_144000.jpg", "created_at": "2024-01-15T14:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 }, { "id": 5, "image": "http://localhost:8000/media/images/post_image_20240115_144001.jpg", "created_at": "2024-01-15T14:30:01Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ] ``` --- ### Update Post URL: PUT /posts/{post_id}/update/ Headers: ```json { "Content-Type": "multipart/form-data", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body (multipart/form-data): ```json content: "Updated post content with more details" images: [new_image1.jpg, new_image2.jpg] ``` Expected Response (200 OK): ```json { "id": 1, "content": "Updated post content with more details", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T13:00:00Z", "is_updated": true, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "images": [ { "id": 6, "image": "http://localhost:8000/media/images/post_image_20240115_150000.jpg", "created_at": "2024-01-15T15:00:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } }, { "id": 7, "image": "http://localhost:8000/media/images/post_image_20240115_150001.jpg", "created_at": "2024-01-15T15:00:01Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } } ], "likes_count": 5, "comments_count": 2, "is_liked": true } ``` --- ### Remove Image from Post URL: DELETE /images/{image_id}/remove/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "message": "Image removed from post successfully" } ``` --- ### Get Post Images URL: GET /images/post/{post_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 3, "next": null, "previous": null, "results": [ { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T12:00:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 }, { "id": 2, "image": "http://localhost:8000/media/images/post_image_20240115_143001.jpg", "created_at": "2024-01-15T12:00:01Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 }, { "id": 3, "image": "http://localhost:8000/media/images/post_image_20240115_143002.jpg", "created_at": "2024-01-15T12:00:02Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ] } ``` --- ### List Posts URL: GET /posts/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 10, "next": "http://localhost:8000/api/posts/?page=2", "previous": null, "results": [ { "id": 1, "content": "This is my first post on this social media platform!", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T12:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "likes_count": 5, "comments_count": 2, "is_liked": true } ] } ``` --- ### Get Post Details URL: GET /posts/{post_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "id": 1, "content": "This is my first post on this social media platform!", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T12:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "likes_count": 5, "comments_count": 2, "is_liked": true } ``` --- ### Update Post URL: PUT /posts/{post_id}/update/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body: ```json { "content": "Updated post content with more details" } ``` Expected Response (200 OK): ```json { "id": 1, "content": "Updated post content with more details", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T13:00:00Z", "is_updated": true, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "likes_count": 5, "comments_count": 2, "is_liked": true } ``` --- ### Delete Post URL: DELETE /posts/{post_id}/delete/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (204 No Content): (no content) --- ### Like Post URL: POST /posts/{post_id}/like/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (201 Created): ```json { "message": "Post liked successfully" } ``` --- ### Unlike Post URL: DELETE /posts/{post_id}/unlike/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "message": "Post unliked successfully" } ``` --- ### Get User Posts URL: GET /posts/user/{user_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 5, "next": null, "previous": null, "results": [ { "id": 1, "content": "This is my first post on this social media platform!", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T12:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "likes_count": 5, "comments_count": 2, "is_liked": true } ] } ``` --- ### Get Category Posts URL: GET /posts/category/{category_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 8, "next": null, "previous": null, "results": [ { "id": 1, "content": "This is my first post on this social media platform!", "created_at": "2024-01-15T12:00:00Z", "updated_at": "2024-01-15T12:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "likes_count": 5, "comments_count": 2, "is_liked": true } ] } ``` --- ### Get Recommended Posts URL: GET /posts/recommended/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 15, "next": "http://localhost:8000/api/posts/recommended/?page=2", "previous": null, "results": [ { "id": 3, "content": "Post from followed user", "created_at": "2024-01-15T14:00:00Z", "updated_at": "2024-01-15T14:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "category": { "id": 2, "title": "Technology", "description": "Tech related posts" }, "likes_count": 8, "comments_count": 3, "is_liked": false } ] } ``` --- ### Get Recent Posts URL: GET /posts/recent/ Headers: ```json { "Content-Type": "application/json" } ``` Expected Response (200 OK): ```json { "count": 20, "next": "http://localhost:8000/api/posts/recent/?page=2", "previous": null, "results": [ { "id": 5, "content": "Latest post on platform", "created_at": "2024-01-15T15:00:00Z", "updated_at": "2024-01-15T15:00:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 3, "username": "bob_wilson", "first_name": "Bob", "last_name": "Wilson" }, "category": { "id": 1, "title": "General", "description": "General posts" }, "likes_count": 2, "comments_count": 1, "is_liked": false } ] } ``` --- ### Get Similar Posts URL: GET /posts/{post_id}/similar/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 3, "next": null, "previous": null, "results": [ { "id": 4, "content": "Another post about similar topic", "created_at": "2024-01-15T13:30:00Z", "updated_at": "2024-01-15T13:30:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "category": { "id": 2, "title": "Technology", "description": "Tech related posts" }, "likes_count": 6, "comments_count": 2, "is_liked": true } ] } ``` --- ### Search Posts URL: GET /posts/search/?q=technology Headers: ```json { "Content-Type": "application/json" } ``` Expected Response (200 OK): ```json { "count": 7, "next": null, "previous": null, "results": [ { "id": 2, "content": "Talking about technology trends", "created_at": "2024-01-15T12:30:00Z", "updated_at": "2024-01-15T12:30:00Z", "is_updated": false, "is_active": true, "created_by": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "category": { "id": 2, "title": "Technology", "description": "Tech related posts" }, "likes_count": 12, "comments_count": 4, "is_liked": false } ] } ``` --- ## Category Management ### Create Category URL: POST /categories/create/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body: ```json { "title": "Technology", "description": "Posts about technology, programming, and innovation" } ``` Expected Response (201 Created): { "id": 2, "title": "Technology", "description": "Posts about technology, programming, and innovation", "created_at": "2024-01-15T11:30:00Z", "updated_at": "2024-01-15T11:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } } ``` --- ### List Categories URL: GET /categories/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 3, "next": null, "previous": null, "results": [ { "id": 1, "title": "General", "description": "General posts and discussions", "created_at": "2024-01-15T10:45:00Z", "updated_at": "2024-01-15T10:45:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } }, { "id": 2, "title": "Technology", "description": "Posts about technology, programming, and innovation", "created_at": "2024-01-15T11:30:00Z", "updated_at": "2024-01-15T11:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } } ] } ``` --- ### Get Category Details URL: GET /categories/{category_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "id": 2, "title": "Technology", "description": "Posts about technology, programming, and innovation", "created_at": "2024-01-15T11:30:00Z", "updated_at": "2024-01-15T11:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "is_following": true, "followers_count": 25, "posts_count": 15 } ``` --- ### Update Category URL: PUT /categories/{category_id}/update/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body: ```json { "title": "Technology & Programming", "description": "Updated description for tech posts" } ``` Expected Response (200 OK): ```json { "id": 2, "title": "Technology & Programming", "description": "Updated description for tech posts", "created_at": "2024-01-15T11:30:00Z", "updated_at": "2024-01-15T14:00:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" } } ``` --- ### Delete Category URL: DELETE /categories/{category_id}/delete/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (204 No Content): (no content) --- ### Follow Category URL: POST /categories/{category_id}/follow/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (201 Created): ```json { "message": "Category followed successfully" } ``` --- ### Unfollow Category URL: DELETE /categories/{category_id}/unfollow/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "message": "Category unfollowed successfully" } ``` --- ## Comment Management ### Create Comment URL: POST /comments/create/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body: ```json { "post": 1, "content": "Great post! I really enjoyed reading this." } ``` Expected Response (201 Created): ```json { "id": 1, "post": 1, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "content": "Great post! I really enjoyed reading this.", "created_at": "2024-01-15T13:00:00Z", "updated_at": "2024-01-15T13:00:00Z", "is_active": true, "likes_count": 0, "is_liked": false } ``` --- ### List Post Comments URL: GET /comments/post/{post_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 3, "next": null, "previous": null, "results": [ { "id": 1, "post": 1, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "content": "Great post! I really enjoyed reading this.", "created_at": "2024-01-15T13:00:00Z", "updated_at": "2024-01-15T13:00:00Z", "is_active": true, "likes_count": 2, "is_liked": true }, { "id": 2, "post": 1, "created_by": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "content": "I agree with your points here!", "created_at": "2024-01-15T13:15:00Z", "updated_at": "2024-01-15T13:15:00Z", "is_active": true, "likes_count": 1, "is_liked": false } ] } ``` --- ### Update Comment URL: PUT /comments/{comment_id}/update/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body: ```json { "content": "Updated comment with additional thoughts" } ``` Expected Response (200 OK): ```json { "id": 1, "post": 1, "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "content": "Updated comment with additional thoughts", "created_at": "2024-01-15T13:00:00Z", "updated_at": "2024-01-15T14:00:00Z", "is_active": true, "likes_count": 2, "is_liked": true } ``` --- ### Delete Comment URL: DELETE /comments/{comment_id}/delete/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (204 No Content): (no content) --- ### Like Comment URL: POST /comments/{comment_id}/like/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (201 Created): ```json { "message": "Comment liked successfully" } ``` --- ### Unlike Comment URL: DELETE /comments/{comment_id}/unlike/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "message": "Comment unliked successfully" } ``` --- ## Like Management ### List Post Likes URL: GET /likes/post/{post_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 5, "next": null, "previous": null, "results": [ { "id": 1, "user": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "post": 1, "created_at": "2024-01-15T12:30:00Z" }, { "id": 2, "user": { "id": 3, "username": "bob_wilson", "first_name": "Bob", "last_name": "Wilson" }, "post": 1, "created_at": "2024-01-15T12:45:00Z" } ] } ``` --- ### List Comment Likes URL: GET /likes/comment/{comment_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 2, "next": null, "previous": null, "results": [ { "id": 3, "user": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "comment": 1, "created_at": "2024-01-15T13:30:00Z" } ] } ``` --- ## Follow Management ### List User Followers URL: GET /follows/user/{user_id}/followers/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 10, "next": null, "previous": null, "results": [ { "id": 1, "follower": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "followed": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "created_at": "2024-01-15T11:00:00Z", "updated_at": "2024-01-15T11:00:00Z" } ] } ``` --- ### List User Following URL: GET /follows/user/{user_id}/following/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 15, "next": null, "previous": null, "results": [ { "id": 2, "follower": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "followed": { "id": 2, "username": "jane_smith", "first_name": "Jane", "last_name": "Smith" }, "created_at": "2024-01-15T11:30:00Z", "updated_at": "2024-01-15T11:30:00Z" } ] } ``` --- ### List Category Followers URL: GET /follows/category/{category_id}/followers/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 25, "next": null, "previous": null, "results": [ { "id": 3, "user": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 2, "title": "Technology", "description": "Posts about technology, programming, and innovation" }, "created_at": "2024-01-15T12:00:00Z" } ] } ``` --- ### List User Followed Categories URL: GET /follows/user/{user_id}/categories/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 5, "next": null, "previous": null, "results": [ { "id": 4, "user": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "category": { "id": 2, "title": "Technology", "description": "Posts about technology, programming, and innovation" }, "created_at": "2024-01-15T12:30:00Z" } ] } ``` --- ## Image Management ### Create Image URL: POST /images/create/ Headers: ```json { "Content-Type": "multipart/form-data", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Body (multipart/form-data): image: [file] post: 1 Expected Response (201 Created): ```json { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T14:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ``` --- ### List Images URL: GET /images/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 8, "next": null, "previous": null, "results": [ { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T14:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ] } ``` --- ### Get Image Details URL: GET /images/{image_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T14:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ``` --- ### Delete Image URL: DELETE /images/{image_id}/delete/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (204 No Content): (no content) --- ### Get Post Images URL: GET /images/post/{post_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 3, "next": null, "previous": null, "results": [ { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T14:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ] } ``` --- ### Get User Images URL: GET /images/user/{user_id}/ Headers: ```json { "Content-Type": "application/json", "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" } ``` Expected Response (200 OK): ```json { "count": 12, "next": null, "previous": null, "results": [ { "id": 1, "image": "http://localhost:8000/media/images/post_image_20240115_143000.jpg", "created_at": "2024-01-15T14:30:00Z", "created_by": { "id": 1, "username": "john_doe", "first_name": "John", "last_name": "Doe" }, "post": 1 } ] } ``` --- ## Error Responses ### Authentication Errors #### Invalid Credentials Status: 401 Unauthorized Response: ```json { "error": "Invalid credentials" } ``` #### Token Not Provided Status: 401 Unauthorized Response: ```json { "detail": "Authentication credentials were not provided." } ``` #### Invalid Token Status: 401 Unauthorized Response: ```json { "detail": "Invalid token." } ``` #### User Inactive Status: 401 Unauthorized Response: ```json { "detail": "User account is disabled." } ``` --- ### Validation Errors #### Missing Required Fields Status: 400 Bad Request Response: ```json { "username": ["This field is required."], "password": ["This field is required."] } ``` #### Invalid Email Format Status: 400 Bad Request Response: ```json { "email": ["Enter a valid email address."] } ``` #### Username Already Exists Status: 400 Bad Request Response: ```json { "username": ["A user with that username already exists."] } ``` #### Password Mismatch Status: 400 Bad Request Response: ```json { "password_confirm": ["Les mots de passe ne correspondent pas."] } ``` --- ### Permission Errors #### Access Denied Status: 403 Forbidden Response: ```json { "detail": "You do not have permission to perform this action." } ``` #### Cannot Follow Self Status: 400 Bad Request Response: ```json { "error": "Vous ne pouvez pas vous suivre vous-même" } ``` #### Already Following Status: 400 Bad Request Response: ```json { "error": "Vous suivez déjà cet utilisateur" } ``` #### Cannot Like Own Post Status: 400 Bad Request Response: ```json { "error": "Vous ne pouvez pas aimer votre propre post" } ``` #### Already Liked Status: 400 Bad Request Response: ```json { "error": "Vous aimez déjà ce post" } ``` --- ### Not Found Errors #### User Not Found Status: 404 Not Found Response: ```json { "error": "Utilisateur non trouvé" } ``` #### Post Not Found Status: 404 Not Found Response: ```json { "error": "Post non trouvé" } ``` #### Category Not Found Status: 404 Not Found Response: ```json { "error": "Catégorie non trouvée" } ``` #### Comment Not Found Status: 404 Not Found Response: ```json { "error": "Commentaire non trouvé" } ``` #### Image Not Found Status: 404 Not Found Response: ```json { "error": "Image non trouvée" } ``` --- ### Server Errors #### Internal Server Error Status: 500 Internal Server Error Response: ```json { "error": "An internal server error occurred" } ``` --- ## Quick Reference ### Authentication Flow 1. POST /auth/register/ - Create account 2. POST /auth/login/ - Get token 3. Use token in Authorization header for all authenticated requests 4. POST /auth/logout/ - Invalidate token ### Common Workflows 1. **Post Management**: Create categories → Create posts → Manage posts 2. **User Interaction**: Follow users → Like posts → Comment 3. **Content Discovery**: Search posts → Get recommendations → View similar posts 4. **Media Management**: Upload images → Attach to posts → Manage media ### Status Codes - **200 OK** - Successful GET, PUT - **201 Created** - Successful POST - **204 No Content** - Successful DELETE - **400 Bad Request** - Validation errors - **401 Unauthorized** - Authentication issues - **403 Forbidden** - Permission issues - **404 Not Found** - Resource not found - **500 Internal Server Error** - Server issues --- ## Notes - All datetime fields use ISO 8601 format - Pagination returns 20 items per page by default - Search is case-insensitive - Ordering uses Django field names with `-` prefix for descending - All authenticated endpoints require valid token - Token-based authentication used throughout API - Soft delete implemented for posts and comments - Users cannot follow themselves or like their own content - Duplicate likes and follows are prevented by unique constraints --- ## Pagination All list endpoints support pagination with the following parameters: - page: Page number (default: 1) - page_size: Number of items per page (default: 20, max: 100) Example: GET /posts/?page=2&page_size=10 --- ## Search and Filtering ### Search Most endpoints support search with the `q` parameter: - GET /posts/search/?q=technology - GET /categories/?q=tech ### Filtering Posts can be filtered by: - category: Filter by category ID - created_by: Filter by user ID - is_active: Filter by active status ### Ordering Results can be ordered with the `ordering` parameter: - GET /posts/?ordering=-created_at (newest first) - GET /posts/?ordering=created_at (oldest first) - GET /posts/?ordering=likes_count (most liked first)