bbs-api.md

Simple Bulletin Board REST API Documentation

Overview

This document outlines the REST API for a simple bulletin board system. The API provides endpoints for posting, retrieving, and deleting comments, with pagination support for comment retrieval.

Base Information

• Base URL: /api/v1
• Response Format: JSON
• Authentication: Not implemented in this simple version

Endpoints

1. Post Comment

Creates a new comment or reply to an existing comment.

Request

• Method: POST
• Endpoint: /comments
• Content-Type: application/json

Request Body

{
  "author": "username",
  "content": "comment text"
}

Response

• Status Code: 201 Created
• Response Body:

{
  "id": "unique comment ID",
  "author": "username",
  "content": "comment text",
  "createdAt": "2025-05-15T10:30:00Z"
}

2. Get Comments (with Pagination)

Retrieves comments with pagination support.

Request

• Method: GET
• Endpoint: /comments
• Query Parameters:
  • page: Page number (default: 1)
  • limit: Number of comments per page (default: 20, max: 100)
  • sort: Sort order (newest/oldest, default: newest)

Response

• Status Code: 200 OK
• Response Body:

{
  "data": [
    {
      "id": "unique comment ID",
      "author": "username",
      "content": "comment text",
      "createdAt": "2025-05-15T10:30:00Z"
    },
    // Multiple comment objects
  ],
  "pagination": {
    "totalComments": 100,
    "totalPages": 5,
    "currentPage": 1,
    "limit": 20,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

3. Delete Comment

Deletes a specific comment by ID.

Request

• Method: DELETE
• Endpoint: /comments/{commentId}
• URL Parameters:
  • commentId: Unique ID of the comment to delete

Response

• Status Code: 204 No Content (Success, no response body)

Error Handling

Common error response format for all API endpoints:

{
  "timestamp": "timestamp in ISO format",
  "status": HTTP status code,
  "error": "HTTP status reason",
  "message": "Detailed error message",
  "path": "URL path"
}

Main error codes:

• 400 Bad Request: Invalid request format
• 404 Not Found: Requested resource not found
• 500 Internal Server Error: Server internal error