This documentation provides all the necessary information to get started with the Web Forum API. It includes instructions for setting up the environment, detailed descriptions of each endpoint, and how to use them effectively to build and manage a web forum.
Before you begin, ensure you have the following installed:
Follow these steps to get your application running:
Clone the Repository
Use Git to clone the source code to your local machine.
git clone <REPOSITORY_SSH_URL>Build the Docker Image
Navigate to the project directory and build the Docker image.
cd <PROJECT_DIRECTORY>
docker build -t web-forum-api .Run the Container
Start the application by running the Docker container.
docker run -p <API_LISTENING_PORT>:<API_LISTENING_PORT> web-forum-apiEndpoint: POST /user/register
Description: Allows new users to register to the web forum by providing a username, password, and email.
Request Body:
{
"username": "newUser123",
"password": "userPassword123",
"email": "newuser123@example.com"
}Response Codes:
201 Created - Registration was successful.400 Bad Request - The provided data was invalid or incomplete.418 I'm a teapot - The email is already associated with an existing account.Endpoint: POST /user/login
Description: Authenticates users by verifying their credentials and initiates a session.
Request Body:
{
"username": "existingUser",
"password": "userPassword123"
}Successful Response:
200 OKResponse Body:
{
"username": "existingUser",
"email": "user@example.com"
}Set-Cookie header with a session cookie.Error Handling:
401 Unauthorized - The username or password is incorrect.Endpoint: POST /categories
Description: Allows for the creation of new categories within the forum. Requires an admin API key for authentication.
Headers: Token: <admin_api_key>
Request Body:
{
"categories": ["Technology", "Health"]
}Response Codes:
201 Created - Successfully created new categories.Endpoint: GET /categories
Description: Retrieves a list of all forum categories, including the default "Default" category.
Successful Response:
200 OK["Default", "Technology", "Health"]Error Handling:
401 Unauthorized - Invalid session cookie or admin API key.Endpoint: POST /thread
Description: Enables authenticated users to create a new thread within a specified category.
Request Body:
{
"category": "Default",
"title": "Exciting Discussion",
"openingPost": {
"text": "Let's talk about something exciting!"
}
}Response Codes:
201 Created - Thread creation was successful.Endpoint: GET /thread
Description: Allows users to retrieve a list of threads filtered by categories, authors, or sorting preferences.
Query Parameters: categories=Default&newest_first=true&page=0&page_size=10
Successful Response:
200 OKResponse Body:
{
"threads": [
{
"id": 1,
"category": "Default",
"title": "Exciting Discussion",
"author": "user123",
"createdAt": "2024-01-01T00:00:00Z"
}
]
}Error Handling:
401 Unauthorized - Requires a valid session cookie.404 Not Found - Requested category does not exist.Endpoint: POST /thread/post
Description: Allows authenticated users to add one or more posts to an existing thread.
Request Body:
{
"threadId": 1,
"posts": [
{"text": "I completely agree with this point!"},
{"text": "Here's an interesting fact that might add to the discussion..."}
]
}Response Codes:
201 Created - Successfully added new posts to the thread.Endpoint: GET /thread/post
Description: Retrieves all posts within a specified thread, facilitating continuous conversation flow.
Query Parameters: thread_id=1
Successful Response:
200 OKResponse Body:
{
"posts": [
{
"author": "user123",
"text": "I completely agree with this point!",
"createdAt": "2024-01-01T01:00:00Z"
},
{
"author": "user456",
"text": "Here's an interesting fact that might add to the discussion...",
"createdAt": "2024-01-01T02:00:00Z"
}
]
}Endpoint: GET /search
Description: Enables users to search for threads containing specific text, improving discoverability and user engagement.
Query Parameters: text=but smith was actually a banana
Successful Response:
200 OKResponse Body:
{
"searchResults": {
"31": [
"...astonishing happened – but Smith was actually a banana. This surreal transformation..."
],
"72": [
"...one amazing day, Smith was actually a banana. What the hell?...."
]
}
}Endpoint: DELETE /thread
Description: Allows administrators to remove threads, maintaining content quality and relevancy.
Query Parameters: id=2
Headers: Token: <admin_api_key>
Response Codes:
204 No Content - Thread successfully deleted.Endpoint: DELETE /categories
Description: Enables forum administration to dynamically manage forum categories.
Query Parameters: category=Tech
Headers: Token: <admin_api_key>
Response Codes:
200 OK - Category successfully deleted.Endpoint: POST /csv
Description: Facilitates bulk user registration through CSV file uploads, streamlining the onboarding process for administrators.
Headers: Token: <admin_api_key>, Content-Type: text/csv
Request Body: CSV content following the format username,password,email.
Successful Response:
201 Created - Indicates that the users have been successfully registered.Error Handling:
400 Bad Request - Invalid CSV format or user data.200 OK - Returned on an empty CSV import.The application requires the following environment variables for configuration:
ADMIN_API_KEY - Secret API key for admin endpoints.API_LISTENING_PORT - Port for the API server.DB_HOST - Hostname for the database server.DB_PASSWORD - Database password.DB_PORT - Database server port.DB_SCHEMA_NAME - Database schema name.DB_USERNAME - Username for database access.