209 lines
7.3 KiB
Markdown
209 lines
7.3 KiB
Markdown
# Blogging API
|
|
|
|
A RESTful API for a blogging platform built with FastAPI and SQLite.
|
|
|
|
## Features
|
|
|
|
- User management with authentication
|
|
- Blog post creation, retrieval, updating, and deletion
|
|
- Comment functionality on blog posts
|
|
- Role-based permissions (regular users and superusers)
|
|
- RESTful API with proper HTTP methods and status codes
|
|
- JWT-based authentication
|
|
- SQLite database with SQLAlchemy ORM
|
|
- Alembic for database migrations
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8+
|
|
- Virtual environment (recommended)
|
|
|
|
## Environment Variables
|
|
|
|
The application uses the following environment variables (see `.env.example` for a template):
|
|
|
|
- `SECRET_KEY`: Secret key for JWT token encryption (default provided for development)
|
|
- `ACCESS_TOKEN_EXPIRE_MINUTES`: JWT token expiration time in minutes (default: 60 * 24 * 8 = 8 days)
|
|
- `PORT`: Port number for the application to listen on (default: 8000)
|
|
- `USE_IN_MEMORY_DB`: Set to "true" to use an in-memory SQLite database (useful for testing or when file access is problematic)
|
|
- `LOG_LEVEL`: Logging level (e.g., DEBUG, INFO, WARNING, ERROR) - defaults to INFO
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd bloggingapi
|
|
```
|
|
|
|
2. Install the dependencies:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Run database migrations:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
4. Run the application:
|
|
|
|
```bash
|
|
# Development mode
|
|
uvicorn main:app --reload
|
|
|
|
# Production mode
|
|
cp .env.example .env # Create and customize your .env file
|
|
python -m uvicorn main:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
The API will be available at http://localhost:8000.
|
|
|
|
## API Documentation
|
|
|
|
Once the application is running, you can access the API documentation at:
|
|
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/login/access-token` - Get JWT access token
|
|
|
|
### Users
|
|
|
|
- `GET /api/v1/users/` - Get all users (superuser only)
|
|
- `POST /api/v1/users/` - Create a new user
|
|
- `GET /api/v1/users/me` - Get current user
|
|
- `PUT /api/v1/users/me` - Update current user
|
|
- `GET /api/v1/users/{user_id}` - Get user by ID
|
|
- `DELETE /api/v1/users/{user_id}` - Delete user (superuser only)
|
|
|
|
### Posts
|
|
|
|
- `GET /api/v1/posts/` - Get all published posts
|
|
- `POST /api/v1/posts/` - Create a new post
|
|
- `GET /api/v1/posts/{post_id}` - Get post by ID
|
|
- `PUT /api/v1/posts/{post_id}` - Update post
|
|
- `DELETE /api/v1/posts/{post_id}` - Delete post
|
|
- `GET /api/v1/posts/user/{user_id}` - Get posts by user
|
|
|
|
### Comments
|
|
|
|
- `GET /api/v1/comments/` - Get all comments (superuser only)
|
|
- `POST /api/v1/comments/` - Create a new comment
|
|
- `GET /api/v1/comments/{comment_id}` - Get comment by ID
|
|
- `PUT /api/v1/comments/{comment_id}` - Update comment
|
|
- `DELETE /api/v1/comments/{comment_id}` - Delete comment
|
|
- `GET /api/v1/comments/post/{post_id}` - Get comments by post
|
|
- `GET /api/v1/comments/user/{user_id}` - Get comments by user
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - API health check
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── .env.example # Environment variables template
|
|
├── alembic.ini # Alembic configuration
|
|
├── app # Application package
|
|
│ ├── api # API endpoints
|
|
│ │ └── v1 # API version 1
|
|
│ │ ├── api.py # API router
|
|
│ │ └── endpoints # API endpoint modules
|
|
│ │ ├── comments.py # Comment endpoints
|
|
│ │ ├── login.py # Authentication endpoints
|
|
│ │ ├── posts.py # Post endpoints
|
|
│ │ └── users.py # User endpoints
|
|
│ ├── auth # Authentication package
|
|
│ │ ├── deps.py # Auth dependencies
|
|
│ │ └── security.py # Security utilities
|
|
│ ├── core # Core package
|
|
│ │ ├── config.py # Configuration settings
|
|
│ │ └── logging.py # Logging configuration
|
|
│ ├── crud # CRUD operations
|
|
│ │ ├── base.py # Base CRUD class
|
|
│ │ ├── comment.py # Comment CRUD
|
|
│ │ ├── post.py # Post CRUD
|
|
│ │ └── user.py # User CRUD
|
|
│ ├── db # Database package
|
|
│ │ ├── base.py # Import all models
|
|
│ │ ├── base_class.py # Base model class
|
|
│ │ └── session.py # Database session
|
|
│ ├── models # SQLAlchemy models
|
|
│ │ ├── comment.py # Comment model
|
|
│ │ ├── post.py # Post model
|
|
│ │ └── user.py # User model
|
|
│ └── schemas # Pydantic schemas
|
|
│ ├── comment.py # Comment schemas
|
|
│ ├── post.py # Post schemas
|
|
│ └── user.py # User schemas
|
|
├── main.py # FastAPI application
|
|
├── migrations # Alembic migrations
|
|
│ ├── env.py # Alembic environment
|
|
│ ├── script.py.mako # Migration script template
|
|
│ └── versions # Migration versions
|
|
│ └── 001_initial_tables.py # Initial migration
|
|
└── requirements.txt # Project dependencies
|
|
```
|
|
|
|
## Development
|
|
|
|
The project uses Alembic for database migrations. To create a new migration after model changes:
|
|
|
|
```bash
|
|
alembic revision --autogenerate -m "Description of changes"
|
|
```
|
|
|
|
To apply migrations:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
### Running in Production
|
|
|
|
For production environments, you may want to use a process manager like systemd, PM2, or Docker to manage the application. Here's an example of running the application in the background using nohup:
|
|
|
|
```bash
|
|
nohup python -m uvicorn main:app --host 0.0.0.0 --port 8000 --log-level info > app.log 2>&1 &
|
|
```
|
|
|
|
To view logs:
|
|
|
|
```bash
|
|
tail -f app.log # Application logs
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter issues with the application starting up:
|
|
|
|
1. Check the application logs where you redirected the output
|
|
2. Verify the database path is correct and accessible
|
|
3. Ensure all environment variables are properly set
|
|
4. Check permissions for the storage directory
|
|
5. Try using the in-memory database option for testing: `USE_IN_MEMORY_DB=true`
|
|
6. Run the application directly with uvicorn to see detailed error messages: `python -m uvicorn main:app --log-level debug`
|
|
7. Check your Python environment and installed packages: `pip list`
|
|
|
|
### Common Issues and Solutions
|
|
|
|
#### Database Access Problems
|
|
|
|
If you encounter database access issues, you can set `USE_IN_MEMORY_DB=true` in your .env file to use an in-memory SQLite database instead of a file-based one. This can help isolate whether the issue is with file permissions or database configuration.
|
|
|
|
#### Process Management
|
|
|
|
If you're using a process manager (like systemd, PM2, etc.) and encounter issues:
|
|
- Make sure all paths are correctly configured
|
|
- Check that the PYTHONPATH environment variable is set correctly
|
|
- Verify that the process manager has permission to run the application
|
|
- Use `python -m uvicorn` instead of just `uvicorn` to ensure the Python module path is correct |