242 lines
6.7 KiB
Markdown
242 lines
6.7 KiB
Markdown
# E-Commerce API
|
|
|
|
A FastAPI-based RESTful API for an e-commerce application with user authentication, product catalog, shopping cart, order processing, and payment processing.
|
|
|
|
## Features
|
|
|
|
- User authentication with JWT
|
|
- Product catalog with categories
|
|
- Shopping cart functionality
|
|
- Order management
|
|
- Mock payment processing
|
|
- Search and filtering products
|
|
- Admin and regular user roles
|
|
|
|
## Technology Stack
|
|
|
|
- **Framework**: FastAPI
|
|
- **Database**: SQLite
|
|
- **ORM**: SQLAlchemy
|
|
- **Migration Tool**: Alembic
|
|
- **Authentication**: JWT with password hashing
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ecommerce-api/
|
|
├── app/
|
|
│ ├── api/
|
|
│ │ ├── deps.py
|
|
│ │ └── v1/
|
|
│ │ ├── api.py
|
|
│ │ └── endpoints/
|
|
│ │ ├── auth.py
|
|
│ │ ├── cart.py
|
|
│ │ ├── categories.py
|
|
│ │ ├── health.py
|
|
│ │ ├── orders.py
|
|
│ │ ├── payments.py
|
|
│ │ ├── products.py
|
|
│ │ └── users.py
|
|
│ ├── core/
|
|
│ │ ├── config.py
|
|
│ │ └── security.py
|
|
│ ├── db/
|
|
│ │ └── session.py
|
|
│ ├── models/
|
|
│ │ ├── base.py
|
|
│ │ ├── cart.py
|
|
│ │ ├── order.py
|
|
│ │ ├── product.py
|
|
│ │ └── user.py
|
|
│ ├── schemas/
|
|
│ │ ├── cart.py
|
|
│ │ ├── order.py
|
|
│ │ ├── product.py
|
|
│ │ ├── token.py
|
|
│ │ └── user.py
|
|
│ └── services/
|
|
├── migrations/
|
|
│ ├── env.py
|
|
│ ├── script.py.mako
|
|
│ └── versions/
|
|
│ └── 0001_create_tables.py
|
|
├── storage/
|
|
│ └── db/
|
|
├── alembic.ini
|
|
├── main.py
|
|
└── requirements.txt
|
|
```
|
|
|
|
## Setup and Installation
|
|
|
|
### 1. Clone the repository
|
|
|
|
```bash
|
|
git clone https://github.com/your-username/ecommerce-api.git
|
|
cd ecommerce-api
|
|
```
|
|
|
|
### 2. Create a virtual environment
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
### 3. Install dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 4. Set up environment variables
|
|
|
|
Create a `.env` file in the root directory:
|
|
|
|
```
|
|
JWT_SECRET_KEY=your_secret_key_here
|
|
```
|
|
|
|
### 5. Initialize the database
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
### 6. Run the application
|
|
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
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/auth/register` - Register a new user with email and password
|
|
- `POST /api/v1/auth/login` - Login with email (provided in the username field) and password to get access token
|
|
|
|
### Users
|
|
|
|
- `GET /api/v1/users/me` - Get current user information
|
|
- `PUT /api/v1/users/me` - Update current user information
|
|
- `GET /api/v1/users/{user_id}` - Get user by ID (admin only)
|
|
- `GET /api/v1/users/` - List all users (admin only)
|
|
|
|
### Categories
|
|
|
|
- `GET /api/v1/categories/` - List all categories
|
|
- `POST /api/v1/categories/` - Create a new category (admin only)
|
|
- `GET /api/v1/categories/{category_id}` - Get category by ID
|
|
- `PUT /api/v1/categories/{category_id}` - Update a category (admin only)
|
|
- `DELETE /api/v1/categories/{category_id}` - Delete a category (admin only)
|
|
|
|
### Products
|
|
|
|
- `GET /api/v1/products/` - List all products (with filtering options)
|
|
- `POST /api/v1/products/` - Create a new product (admin only)
|
|
- `GET /api/v1/products/{product_id}` - Get product by ID
|
|
- `PUT /api/v1/products/{product_id}` - Update a product (admin only)
|
|
- `DELETE /api/v1/products/{product_id}` - Delete a product (admin only)
|
|
|
|
### Cart
|
|
|
|
- `GET /api/v1/cart/` - Get user's cart
|
|
- `POST /api/v1/cart/items` - Add item to cart
|
|
- `PUT /api/v1/cart/items/{item_id}` - Update cart item quantity
|
|
- `DELETE /api/v1/cart/items/{item_id}` - Remove item from cart
|
|
- `DELETE /api/v1/cart/` - Clear cart
|
|
|
|
### Orders
|
|
|
|
- `GET /api/v1/orders/` - List user's orders (admin can see all)
|
|
- `POST /api/v1/orders/` - Create a new order from cart
|
|
- `GET /api/v1/orders/{order_id}` - Get order by ID
|
|
- `PUT /api/v1/orders/{order_id}` - Update order (limited for regular users)
|
|
- `DELETE /api/v1/orders/{order_id}` - Cancel order
|
|
|
|
### Payments
|
|
|
|
- `POST /api/v1/payments/` - Process payment for an order
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - Application health check
|
|
- `GET /api/v1/health/` - Detailed health check
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| JWT_SECRET_KEY | Secret key for JWT token generation | supersecretkey |
|
|
| JWT_ALGORITHM | Algorithm used for JWT | HS256 |
|
|
| ACCESS_TOKEN_EXPIRE_MINUTES | Token expiration time in minutes | 30 |
|
|
|
|
## Database
|
|
|
|
The application uses SQLite as the database. The database file is created at `/app/storage/db/db.sqlite`.
|
|
|
|
## CORS Configuration
|
|
|
|
The API has robust CORS (Cross-Origin Resource Sharing) enabled with the following configuration:
|
|
|
|
- Allowed origins:
|
|
- http://localhost
|
|
- http://localhost:3000
|
|
- http://127.0.0.1
|
|
- http://127.0.0.1:3000
|
|
- https://v0-ecommerce-app-build-swart.vercel.app
|
|
- https://*.vercel.app (for preview deployments)
|
|
- * (wildcard for development)
|
|
|
|
- Allowed methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
|
|
- Allowed headers:
|
|
- Authorization
|
|
- Content-Type
|
|
- Accept
|
|
- Accept-Language
|
|
- Content-Language
|
|
- Content-Length
|
|
- Origin
|
|
- X-Requested-With
|
|
- X-CSRF-Token
|
|
- Access-Control-Allow-Origin
|
|
- Access-Control-Allow-Credentials
|
|
- X-HTTP-Method-Override
|
|
|
|
- Exposed headers: Content-Length, Content-Type, Authorization
|
|
- Credentials support: Enabled (supports JWT authentication)
|
|
- Max age for preflight requests: 3600 seconds (1 hour)
|
|
|
|
### Custom CORS Handling
|
|
|
|
This application implements a custom CORS middleware that properly handles preflight OPTIONS requests for all endpoints, including authentication routes. The middleware includes:
|
|
|
|
1. Direct handling of OPTIONS requests for all endpoints
|
|
2. Proper header handling for preflight responses
|
|
3. Explicit support for POST requests with JSON content-type
|
|
4. Full support for Authorization headers for authenticated endpoints
|
|
5. Pattern matching for wildcard domains (e.g., *.vercel.app)
|
|
|
|
### CORS Test Endpoint
|
|
|
|
The API includes a special endpoint for testing CORS functionality:
|
|
|
|
- `OPTIONS /api/v1/cors-test` - Test preflight requests
|
|
- `POST /api/v1/cors-test` - Test POST requests with JSON body
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| USE_CUSTOM_CORS_ONLY | Whether to use only the custom CORS middleware | True | |