Bog - FastAPI Micro-Blogging API

A modern, secure micro-blogging API built with FastAPI

What is Bog?

Bog is a straightforward yet powerful FastAPI backend for a micro-blogging social media platform. It provides all the essential features you'd expect from a modern social platform: user registration, secure authentication, post creation and management, social following, post likes, and personalized feeds.

Key Features

• Secure JWT Authentication - Token-based auth with bcrypt password hashing
• User Management - Registration, profiles, and user discovery
• Post System - Create, update, delete, and manage blog posts
• Social Interactions - Like/unlike posts and follow/unfollow users
• Feed System - Discover users and view user-specific post feeds
• Fast & Modern - Built with FastAPI for high performance
• Docker Ready - Containerized for easy deployment
• Auto-Generated Docs - Interactive API documentation with Swagger UI

Tech Stack

• Framework: FastAPI
• Database: SQLite with SQLAlchemy ORM
• Authentication: JWT tokens with passlib (bcrypt)
• Validation: Pydantic models
• Containerization: Docker & Docker Compose
• Documentation: Automatic OpenAPI/Swagger docs

Quick Start

Local Development Setup

1. Clone the Repository

git clone https://github.com/TheRootDaemon/bog.git
cd bog

2. Create Virtual Environment

# Uses uv as the default package manager
uv venv .venv

uv sync

3. Run the Application

uvicorn app.main:app --reload

4. Access the API
   • API Server: http://localhost:8000
   • Interactive Docs: http://localhost:8000/docs

Docker Deployment

Using Docker Compose (Recommended)

# Clone and navigate to project
git clone https://github.com/TheRootDaemon/bog.git
cd bog

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

The API will be available at http://localhost:10000

API Reference

Authentication

Method	Endpoint	Description	Auth Required
POST	/auth/token	Login and get JWT token	❌

Users

Method	Endpoint	Description	Auth Required
POST	/users	Register a new user	❌
POST	/users/{user_id}/follow	Follow a user	✅
DELETE	/users/{user_id}/unfollow	Unfollow a user	✅

Posts

Method	Endpoint	Description	Auth Required
POST	/posts	Create a new post	✅
PUT	/posts/{post_id}	Update your post	✅
DELETE	/posts/{post_id}	Delete your post	✅
POST	/posts/{post_id}/like	Like a post	✅
DELETE	/posts/{post_id}/like	Unlike a post	✅

Feed

Method	Endpoint	Description	Auth Required
GET	/feed	Get random users for discovery	❌
GET	/feed/{username}	Get posts by username	❌

General

Method	Endpoint	Description	Auth Required
GET	/	API health check	❌
GET	/user	Get current user info	✅

Usage Examples

Register a New User

curl -X POST "http://localhost:8000/users" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "[email protected]",
    "gender": "male",
    "password": "securepassword123"
  }'

Login and Get Token

curl -X POST "http://localhost:8000/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=johndoe&password=securepassword123"

Create a Post

curl -X POST "http://localhost:8000/posts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "My First Post",
    "content": "Hello, Bog community! This is my first post."
  }'

Follow a User

curl -X POST "http://localhost:8000/users/2/follow" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Like a Post

curl -X POST "http://localhost:8000/posts/1/like" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get User Feed

curl -X GET "http://localhost:8000/feed/johndoe"

Project Structure

bog/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app initialization
│   ├── database.py          # Database configuration
│   ├── models.py            # SQLAlchemy ORM models
│   ├── schemas.py           # Pydantic request/response models
│   └── routes/
│       ├── __init__.py
│       ├── auth.py          # Authentication endpoints
│       ├── registerUser.py  # User registration
│       ├── follow.py        # Follow/unfollow functionality
│       ├── posts.py         # Post management
│       └── feed.py          # Feed endpoints
├── blog.db                  # SQLite database file
├── requirements.txt         # Python dependencies
├── dockerfile              # Docker configuration
├── compose.yml             # Docker Compose configuration
└── README.md               # This file

Authentication Flow

1. Register: Create a new user account via /users
2. Login: Get JWT token via /auth/token
3. Authenticate: Include token in Authorization: Bearer <token> header
4. Access: Use token to access protected endpoints

Database Schema

Users Table

• id (Primary Key)
• username (Unique)
• email
• gender
• password (Hashed)

Posts Table

• id (Primary Key)
• author (Foreign Key to Users)
• title
• content

Relationships

• Follow: Many-to-many relationship between users
• Likes: Many-to-many relationship between users and posts

Response Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
422	Validation Error

The Swagger UI provides a complete interface to test all endpoints with proper authentication.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Made with ❤️ using FastAPI