Skip to content

NewsBox Service API

Port 3004 newsbox_db

The NewsBox service powers the community-driven news feed with posts, comments, and voting functionality.

Overview

Property Value
Port 3004
Database newsbox_db
Base Path /api/newsbox
Auth Required Partial (viewing is public, actions require auth)

Database Schema

Tables

erDiagram
    categories ||--o{ posts : has
    posts ||--o{ comments : has
    posts ||--o{ post_votes : has
    comments ||--o{ comment_votes : has

    categories {
        uuid id PK
        varchar name UK
        timestamp created_at
    }

    posts {
        uuid id PK
        uuid author_id
        varchar author_name
        varchar title
        text content
        text[] images
        uuid category_id FK
        boolean is_official
        boolean is_pinned
        varchar status
        timestamp created_at
        timestamp updated_at
    }

    comments {
        uuid id PK
        uuid post_id FK
        uuid author_id
        varchar author_name
        text content
        timestamp created_at
        timestamp updated_at
    }

    post_votes {
        uuid id PK
        uuid user_id
        uuid post_id FK
        varchar vote_type
    }

    comment_votes {
        uuid id PK
        uuid user_id
        uuid comment_id FK
        varchar vote_type
    }

Default Categories

  • Campus
  • Sports
  • Academics
  • Career
  • Lifestyle
  • Tech
  • Emergency
  • Events

API Endpoints

Categories

Get All Categories

GET /categories

Returns all available post categories.

{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "name": "Campus",
            "created_at": "2024-01-15T10:00:00Z"
        }
    ]
}

Create Category (Admin)

POST /categories

Admin Only

Requires admin authentication.

{
    "name": "New Category"
}

{
    "success": true,
    "data": {
        "id": "uuid",
        "name": "New Category",
        "created_at": "2024-01-15T10:00:00Z"
    }
}

Posts

Get All Posts

GET /posts

Returns all approved posts with optional filtering.

Query Parameters:

Parameter Type Description
category string Filter by category name
author_id uuid Filter by author
status string Filter by status (admin only)
limit number Results per page (default: 20)
offset number Pagination offset 
{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "author_id": "uuid",
            "author_name": "John Doe",
            "title": "Campus Event Announcement",
            "content": "Lorem ipsum...",
            "images": ["https://..."],
            "category_id": "uuid",
            "category_name": "Events",
            "is_official": false,
            "is_pinned": false,
            "status": "APPROVED",
            "upvotes": 15,
            "downvotes": 2,
            "comment_count": 5,
            "created_at": "2024-01-15T10:00:00Z"
        }
    ]
}

Get Post by ID

GET /posts/:id

Returns a single post with its comments.

{
    "success": true,
    "data": {
        "id": "uuid",
        "author_id": "uuid",
        "author_name": "John Doe",
        "title": "Campus Event",
        "content": "Full content...",
        "images": [],
        "category_name": "Events",
        "is_official": false,
        "is_pinned": false,
        "status": "APPROVED",
        "upvotes": 15,
        "downvotes": 2,
        "comments": [
            {
                "id": "uuid",
                "author_name": "Jane Smith",
                "content": "Great post!",
                "upvotes": 3,
                "downvotes": 0,
                "created_at": "2024-01-15T11:00:00Z"
            }
        ],
        "created_at": "2024-01-15T10:00:00Z"
    }
}

Create Post

POST /posts

Authentication Required

Requires valid JWT token.

{
    "title": "My New Post",
    "content": "Post content here...",
    "category_id": "uuid",
    "images": ["base64 or URL"]
}

{
    "success": true,
    "data": {
        "id": "uuid",
        "title": "My New Post",
        "status": "PENDING",
        "created_at": "2024-01-15T10:00:00Z"
    },
    "message": "Post created and pending approval"
}

Update Post

PUT /posts/:id

Update a post (author or admin only).

{
    "title": "Updated Title",
    "content": "Updated content"
}

Delete Post

DELETE /posts/:id

Delete a post (author or admin only).

Voting

Vote on Post

POST /posts/:id/vote

Authentication Required

{
    "vote_type": "UP"
}

Vote types: UP, DOWN, or null to remove vote.

{
    "success": true,
    "data": {
        "upvotes": 16,
        "downvotes": 2
    }
}

Vote on Comment

POST /comments/:id/vote

{
    "vote_type": "UP"
}

Comments

Add Comment

POST /posts/:id/comments

Authentication Required

{
    "content": "This is my comment"
}

{
    "success": true,
    "data": {
        "id": "uuid",
        "post_id": "uuid",
        "author_name": "Current User",
        "content": "This is my comment",
        "created_at": "2024-01-15T12:00:00Z"
    }
}

Get Post Comments

GET /posts/:id/comments

Returns all comments for a post.

Delete Comment

DELETE /comments/:id

Delete a comment (author only).

Admin Endpoints

Get Pending Posts

GET /admin/posts/pending

Admin Only

Returns all posts awaiting approval.

Update Post Status

PATCH /admin/posts/:id/status

{
    "status": "APPROVED"
}

Status options: PENDING, APPROVED, REJECTED

Toggle Pin Status

PATCH /admin/posts/:id/pin

Pin or unpin a post to the top of the feed.

Post Status Workflow

stateDiagram-v2
    [*] --> PENDING: Create Post
    PENDING --> APPROVED: Admin Approves
    PENDING --> REJECTED: Admin Rejects
    APPROVED --> [*]: Visible to All
    REJECTED --> [*]: Hidden

Error Codes

Code Message Description
400 Invalid request Missing required fields
401 Unauthorized Missing or invalid JWT
403 Forbidden Not author or admin
404 Post not found Invalid post ID
409 Already voted User already voted