Gunpla API

A RESTful API for managing Gunpla (Gundam model kit) listings and orders. Built with Node.js, Express, and PostgreSQL.

Features

• User Authentication: JWT-based authentication for secure access
• Product Listings: Browse and search Gunpla kits with filtering options
• Order Management: Create and manage orders with inventory tracking
• Database Transactions: ACID-compliant transactions to prevent overselling
• Input Validation: Comprehensive validation for all API endpoints
• Pagination: Support for paginated results on listings

Tech Stack

• Backend: Node.js, Express.js
• Database: PostgreSQL with connection pooling
• Authentication: JSON Web Tokens (JWT)
• Environment: dotenv for configuration management
• Development: nodemon for auto-restart during development

Installation

1. Clone the repository:

git clone <repository-url>
cd gunpla-api

2. Install dependencies:

npm install

3. Set up environment variables: Create a .env file in the root directory with the following variables:

PORT=3000
DATABASE_URL=postgresql://username:password@localhost:5432/database_name
JWT_SECRET=your-secret-key-change-in-production
SHIPPING_CENTS=799
TAX_RATE=0

4. Start the development server:

npm run dev

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

API Endpoints

Health Check

• GET /health - Check API and database connectivity

Listings

• GET /listings - Get all active listings with filtering and pagination

Query Parameters:

• q - Search query for kit name (fuzzy match)
• grade - Filter by kit grade (e.g., HG, RG, MG)
• minPrice - Minimum price in cents
• maxPrice - Maximum price in cents
• limit - Results per page (default: 20, max: 100)
• offset - Pagination offset (default: 0)

Orders

• POST /orders - Create a new order (requires authentication)

Headers:

• Authorization: Bearer <token>

Request Body:

{
  "buyerEmail": "user@example.com",
  "listingId": 123,
  "qty": 2
}

Database Schema

The API uses the following main tables:

• users - User information
• gunpla_kits - Gunpla kit catalog
• listings - Active product listings with inventory
• orders - Order information
• order_items - Order line items

Security Features

• JWT authentication for all protected endpoints
• Input validation and sanitization
• SQL injection protection with parameterized queries
• Row-level locking to prevent race conditions during order creation
• Inventory management with atomic updates

Development

Code Style

The code follows standard JavaScript/Node.js conventions with:

• Consistent indentation and formatting
• Descriptive variable and function names
• Proper error handling with try-catch blocks
• Database transactions for critical operations

Testing

To add tests, consider using:

• Jest for unit testing
• Supertest for API endpoint testing
• Test database setup for integration tests

Production Deployment

Before deploying to production:

1. Set a strong JWT_SECRET environment variable
2. Configure proper CORS settings
3. Enable HTTPS
4. Set up proper logging (consider Winston)
5. Configure database connection pooling for your environment
6. Add rate limiting and monitoring

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions, please create an issue in the GitHub repository.