View file File name : COMMUNITY_API_DOCUMENTATION.md Content :# Community Module API Documentation Complete REST API documentation for the Community Module. ## Base URL ``` https://your-domain.com/api/v1 ``` ## Authentication Most endpoints require authentication using Laravel Sanctum tokens. **Headers:** ``` Authorization: Bearer {token} Content-Type: application/json Accept: application/json ``` --- ## Communities API ### 1. Get All Communities Retrieve a paginated list of all active communities. **Endpoint:** `GET /communities` **Query Parameters:** - `search` (string, optional) - Search by name or description - `app_id` (integer, optional) - Filter by app ID - `sort_by` (string, optional) - Sort field (default: `created_at`) - `sort_order` (string, optional) - Sort order `asc` or `desc` (default: `desc`) - `per_page` (integer, optional) - Items per page (default: 15) - `page` (integer, optional) - Page number **Example Request:** ```bash curl -X GET "https://your-domain.com/api/v1/communities?search=gaming&per_page=10" \ -H "Accept: application/json" ``` **Example Response:** ```json { "data": [ { "id": 1, "name": "Gaming Community", "slug": "gaming-community", "description": "A community for gamers", "banner_image": "https://your-domain.com/storage/community-banners/image.jpg", "is_active": true, "allow_posts": true, "moderate_posts": false, "app": { "id": 1, "name": "My Gaming App", "slug": "my-gaming-app" }, "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } ], "links": { "first": "https://your-domain.com/api/v1/communities?page=1", "last": "https://your-domain.com/api/v1/communities?page=5", "prev": null, "next": "https://your-domain.com/api/v1/communities?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 5, "per_page": 15, "to": 15, "total": 75 } } ``` --- ### 2. Get Single Community Retrieve details of a specific community. **Endpoint:** `GET /communities/{slug}` **Example Request:** ```bash curl -X GET "https://your-domain.com/api/v1/communities/gaming-community" \ -H "Accept: application/json" ``` **Example Response:** ```json { "data": { "id": 1, "name": "Gaming Community", "slug": "gaming-community", "description": "A community for gamers", "banner_image": "https://your-domain.com/storage/community-banners/image.jpg", "is_active": true, "allow_posts": true, "moderate_posts": false, "app": { "id": 1, "name": "My Gaming App", "slug": "my-gaming-app" }, "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } } ``` --- ### 3. Create Community Create a new community for an app. **Requires Authentication**. **Endpoint:** `POST /communities` **Request Body:** ```json { "app_id": 1, "name": "Gaming Community", "description": "A community for gamers", "banner_image": "file upload", "allow_posts": true, "moderate_posts": false } ``` **Example Request:** ```bash curl -X POST "https://your-domain.com/api/v1/communities" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" \ -F "app_id=1" \ -F "name=Gaming Community" \ -F "description=A community for gamers" \ -F "banner_image=@/path/to/image.jpg" \ -F "allow_posts=true" \ -F "moderate_posts=false" ``` **Example Response:** ```json { "data": { "id": 1, "name": "Gaming Community", "slug": "gaming-community", "description": "A community for gamers", "banner_image": "https://your-domain.com/storage/community-banners/image.jpg", "is_active": true, "allow_posts": true, "moderate_posts": false, "app": { "id": 1, "name": "My Gaming App", "slug": "my-gaming-app" }, "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } } ``` --- ### 4. Update Community Update an existing community. **Requires Authentication**. **Endpoint:** `PUT /communities/{slug}` **Request Body:** ```json { "name": "Updated Gaming Community", "description": "An updated description", "is_active": true, "allow_posts": true, "moderate_posts": true } ``` **Example Request:** ```bash curl -X PUT "https://your-domain.com/api/v1/communities/gaming-community" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Updated Gaming Community", "description": "An updated description" }' ``` --- ### 5. Delete Community Delete a community. **Requires Authentication**. **Endpoint:** `DELETE /communities/{slug}` **Example Request:** ```bash curl -X DELETE "https://your-domain.com/api/v1/communities/gaming-community" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" ``` **Example Response:** ```json { "message": "Community deleted successfully" } ``` --- ## Posts API ### 1. Get All Posts Retrieve a paginated list of approved posts. **Endpoint:** `GET /posts` **Query Parameters:** - `community_id` (integer, optional) - Filter by community ID - `community_slug` (string, optional) - Filter by community slug - `search` (string, optional) - Search by title or content - `sort_by` (string, optional) - `created_at`, `likes_count`, or `popular` (default: `created_at`) - `sort_order` (string, optional) - `asc` or `desc` (default: `desc`) - `pinned` (boolean, optional) - Get only pinned posts - `per_page` (integer, optional) - Items per page (default: 15) - `page` (integer, optional) - Page number **Example Request:** ```bash curl -X GET "https://your-domain.com/api/v1/posts?community_slug=gaming-community&sort_by=popular" \ -H "Accept: application/json" ``` **Example Response:** ```json { "data": [ { "id": 1, "title": "Welcome to the Gaming Community!", "content": "This is the first post in our gaming community...", "image": "https://your-domain.com/storage/community-posts/image.jpg", "is_pinned": true, "is_approved": true, "likes_count": 45, "comments_count": 12, "user": { "id": 1, "name": "John Doe", "email": "john@example.com" }, "community": { "id": 1, "name": "Gaming Community", "slug": "gaming-community" }, "is_liked_by_user": false, "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } ], "links": {...}, "meta": {...} } ``` --- ### 2. Get Single Post Retrieve details of a specific post including comments. **Endpoint:** `GET /posts/{id}` **Example Request:** ```bash curl -X GET "https://your-domain.com/api/v1/posts/1" \ -H "Accept: application/json" ``` **Example Response:** ```json { "data": { "id": 1, "title": "Welcome to the Gaming Community!", "content": "This is the first post...", "image": "https://your-domain.com/storage/community-posts/image.jpg", "is_pinned": true, "is_approved": true, "likes_count": 45, "comments_count": 12, "user": { "id": 1, "name": "John Doe", "email": "john@example.com" }, "community": { "id": 1, "name": "Gaming Community", "slug": "gaming-community" }, "is_liked_by_user": false, "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } } ``` --- ### 3. Create Post Create a new post in a community. **Requires Authentication**. **Endpoint:** `POST /posts` **Request Body:** ```json { "community_id": 1, "title": "My First Post", "content": "This is my first post in the community...", "image": "file upload" } ``` **Example Request:** ```bash curl -X POST "https://your-domain.com/api/v1/posts" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" \ -F "community_id=1" \ -F "title=My First Post" \ -F "content=This is my first post in the community..." \ -F "image=@/path/to/image.jpg" ``` **Example Response:** ```json { "data": { "id": 2, "title": "My First Post", "content": "This is my first post in the community...", "image": "https://your-domain.com/storage/community-posts/image.jpg", "is_pinned": false, "is_approved": true, "likes_count": 0, "comments_count": 0, "user": { "id": 1, "name": "John Doe", "email": "john@example.com" }, "community": { "id": 1, "name": "Gaming Community", "slug": "gaming-community" }, "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } } ``` --- ### 4. Update Post Update an existing post. **Requires Authentication** (only post author). **Endpoint:** `PUT /posts/{id}` **Request Body:** ```json { "title": "Updated Title", "content": "Updated content..." } ``` **Example Request:** ```bash curl -X PUT "https://your-domain.com/api/v1/posts/2" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "title": "Updated Title", "content": "Updated content..." }' ``` --- ### 5. Delete Post Delete a post. **Requires Authentication** (post author or super admin). **Endpoint:** `DELETE /posts/{id}` **Example Request:** ```bash curl -X DELETE "https://your-domain.com/api/v1/posts/2" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" ``` **Example Response:** ```json { "message": "Post deleted successfully" } ``` --- ### 6. Toggle Like on Post Like or unlike a post. **Requires Authentication**. **Endpoint:** `POST /posts/{id}/like` **Example Request:** ```bash curl -X POST "https://your-domain.com/api/v1/posts/1/like" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" ``` **Example Response:** ```json { "message": "Post liked", "liked": true, "likes_count": 46 } ``` --- ## Comments API ### 1. Get All Comments Retrieve comments for a post. **Endpoint:** `GET /comments` **Query Parameters:** - `post_id` (integer, required) - Filter by post ID - `per_page` (integer, optional) - Items per page (default: 20) - `page` (integer, optional) - Page number **Example Request:** ```bash curl -X GET "https://your-domain.com/api/v1/comments?post_id=1" \ -H "Accept: application/json" ``` **Example Response:** ```json { "data": [ { "id": 1, "content": "Great post!", "user": { "id": 2, "name": "Jane Smith", "email": "jane@example.com" }, "post_id": 1, "parent_id": null, "replies": [ { "id": 2, "content": "Thanks!", "user": { "id": 1, "name": "John Doe", "email": "john@example.com" }, "post_id": 1, "parent_id": 1, "created_at": "2025-10-20T14:40:00.000000Z", "updated_at": "2025-10-20T14:40:00.000000Z" } ], "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } ], "links": {...}, "meta": {...} } ``` --- ### 2. Get Single Comment Retrieve details of a specific comment. **Endpoint:** `GET /comments/{id}` **Example Request:** ```bash curl -X GET "https://your-domain.com/api/v1/comments/1" \ -H "Accept: application/json" ``` --- ### 3. Create Comment Create a new comment on a post. **Requires Authentication**. **Endpoint:** `POST /comments` **Request Body:** ```json { "post_id": 1, "parent_id": null, "content": "This is my comment" } ``` **Example Request:** ```bash curl -X POST "https://your-domain.com/api/v1/comments" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "post_id": 1, "content": "This is my comment" }' ``` **Example Response:** ```json { "data": { "id": 3, "content": "This is my comment", "user": { "id": 1, "name": "John Doe", "email": "john@example.com" }, "post_id": 1, "parent_id": null, "replies": [], "created_at": "2025-10-20T14:36:07.000000Z", "updated_at": "2025-10-20T14:36:07.000000Z" } } ``` --- ### 4. Create Reply to Comment Create a reply to an existing comment. **Requires Authentication**. **Request Body:** ```json { "post_id": 1, "parent_id": 1, "content": "This is a reply" } ``` --- ### 5. Update Comment Update an existing comment. **Requires Authentication** (only comment author). **Endpoint:** `PUT /comments/{id}` **Request Body:** ```json { "content": "Updated comment content" } ``` **Example Request:** ```bash curl -X PUT "https://your-domain.com/api/v1/comments/3" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "content": "Updated comment content" }' ``` --- ### 6. Delete Comment Delete a comment. **Requires Authentication** (comment author or super admin). **Endpoint:** `DELETE /comments/{id}` **Example Request:** ```bash curl -X DELETE "https://your-domain.com/api/v1/comments/3" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" ``` **Example Response:** ```json { "message": "Comment deleted successfully" } ``` --- ## Error Responses All endpoints return consistent error responses: **Validation Error (422):** ```json { "message": "The given data was invalid.", "errors": { "title": [ "The title field is required." ], "content": [ "The content must be at least 10 characters." ] } } ``` **Unauthorized (401):** ```json { "message": "Unauthenticated." } ``` **Forbidden (403):** ```json { "message": "Unauthorized" } ``` **Not Found (404):** ```json { "message": "No query results for model [App\\Models\\Community] gaming-community" } ``` --- ## Rate Limiting API requests are rate-limited to prevent abuse. Default limits: - Authenticated requests: 60 requests per minute - Unauthenticated requests: 30 requests per minute Rate limit headers are included in responses: ``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 59 ``` --- ## Authentication Setup To authenticate with the API, users need to create a Sanctum token: ```php // Generate token $token = $user->createToken('api-token')->plainTextToken; ``` Then use this token in the Authorization header: ``` Authorization: Bearer {token} ``` --- ## Complete Feature Set - Browse and search communities across multiple apps - Filter communities by app - Create posts with images - Comment on posts with nested replies - Like/unlike posts - Moderation support (approve posts, pin posts) - Soft deletes for posts and comments - Authorization checks (users can only edit their own content) - Pagination on all list endpoints - Full-text search capabilities - Image upload support --- ## Notes - All timestamps are in ISO 8601 format - Image uploads must be less than 2MB - Posts require minimum 5 characters for title and 10 for content - Comments can be up to 1000 characters - Nested comments are supported (replies to comments) - Soft deleted posts and comments can be restored by administrators