API Reference

Complete reference for all Elite Events API endpoints.

Base URL: http://localhost:3000/api (development)

Version: 1.0.0

Authentication
Products
Categories
Cart
Wishlist
User
Reviews
Orders
Admin
Error Handling
Rate Limiting

Authentication

All endpoints requiring authentication expect a valid NextAuth session cookie.

Register User

POST /api/auth/signup

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123"
}

Response: 200 OK

{
  "success": true,
  "message": "User created successfully"
}

Errors:

400 Bad Request - Validation failed
409 Conflict - Email already registered

Handled by NextAuth.js

POST /api/auth/signin
Content-Type: application/x-www-form-urlencoded

email=john@example.com&password=password123

Response: Redirects to callback URL with session cookie

Logout

POST /api/auth/signout

Response: Redirects to homepage, clears session

Check Session

GET /api/auth/session

Response: 200 OK

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role": "CUSTOMER"
  },
  "expires": "2024-12-20T12:00:00.000Z"
}

Products

List Products

GET /api/products?page=1&limit=20&categoryId=1&search=tent

Query Parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page
`categoryId`	number	-	Filter by category
`search`	string	-	Search in title
`minPrice`	number	-	Minimum price
`maxPrice`	number	-	Maximum price
`inStock`	boolean	-	Only in-stock items

Response: 200 OK

{
  "products": [
    {
      "id": 1,
      "title": "Frame Tent 20x20",
      "description": "Professional frame tent",
      "price": 299.99,
      "discountedPrice": 249.99,
      "stock": 5,
      "sku": "TENT-FR-2020",
      "categoryId": 8,
      "category": {
        "id": 8,
        "title": "Frame Tents"
      },
      "images": [
        {
          "id": 1,
          "url": "/images/products/product-1-bg-1.webp",
          "type": "PREVIEW"
        }
      ],
      "reviews": []
    }
  ],
  "pagination": {
    "total": 90,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}

Get Product by ID

GET /api/products/[id]

Response: 200 OK

{
  "id": 1,
  "title": "Frame Tent 20x20",
  "description": "Professional frame tent for events",
  "price": 299.99,
  "discountedPrice": 249.99,
  "stock": 5,
  "sku": "TENT-FR-2020",
  "categoryId": 8,
  "category": {
    "id": 8,
    "title": "Frame Tents",
    "parentId": 2
  },
  "images": [
    {
      "id": 1,
      "url": "/images/products/product-1-bg-1.webp",
      "type": "PREVIEW",
      "order": 1
    },
    {
      "id": 2,
      "url": "/images/products/product-1-sm-1.webp",
      "type": "THUMBNAIL",
      "order": 1
    }
  ],
  "reviews": [
    {
      "id": 1,
      "rating": 5,
      "comment": "Excellent tent!",
      "userId": 2,
      "user": {
        "name": "Jane Doe"
      },
      "createdAt": "2024-11-15T10:00:00.000Z"
    }
  ],
  "averageRating": 4.5,
  "reviewCount": 12
}

Errors:

404 Not Found - Product doesn't exist

Cart

Authentication Required

Get Cart

GET /api/cart

Response: 200 OK

{
  "items": [
    {
      "id": 1,
      "productId": 5,
      "quantity": 2,
      "product": {
        "id": 5,
        "title": "Bounce House Castle",
        "price": 199.99,
        "discountedPrice": 179.99,
        "images": [...]
      },
      "subtotal": 359.98
    }
  ],
  "total": 359.98,
  "itemCount": 2
}

Add to Cart

POST /api/cart
Content-Type: application/json

Request Body:

{
  "productId": 5,
  "quantity": 1
}

Response: 201 Created

{
  "success": true,
  "message": "Product added to cart",
  "item": {
    "id": 1,
    "productId": 5,
    "quantity": 1
  }
}

Errors:

400 Bad Request - Invalid product ID or quantity
404 Not Found - Product doesn't exist
401 Unauthorized - Not logged in

Update Cart Item

PATCH /api/cart/[id]
Content-Type: application/json

Request Body:

{
  "quantity": 3
}

Response: 200 OK

{
  "success": true,
  "message": "Cart updated",
  "item": {
    "id": 1,
    "quantity": 3
  }
}

Remove from Cart

DELETE /api/cart/[id]

Response: 200 OK

{
  "success": true,
  "message": "Item removed from cart"
}

Wishlist

Authentication Required

Get Wishlist

GET /api/wishlist

Response: 200 OK

{
  "items": [
    {
      "id": 1,
      "productId": 10,
      "product": {
        "id": 10,
        "title": "Popcorn Machine",
        "price": 75.00,
        "discountedPrice": 65.00,
        "images": [...]
      },
      "addedAt": "2024-11-18T10:00:00.000Z"
    }
  ],
  "count": 1
}

Add to Wishlist

POST /api/wishlist
Content-Type: application/json

Request Body:

{
  "productId": 10
}

Response: 201 Created

{
  "success": true,
  "message": "Added to wishlist",
  "item": {
    "id": 1,
    "productId": 10
  }
}

Remove from Wishlist

DELETE /api/wishlist/[id]

Response: 200 OK

{
  "success": true,
  "message": "Removed from wishlist"
}

User

Authentication Required

Get User Profile

GET /api/user/profile

Response: 200 OK

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "role": "CUSTOMER",
  "createdAt": "2024-10-01T00:00:00.000Z"
}

Update Profile

PATCH /api/user/profile
Content-Type: application/json

Request Body:

{
  "name": "John Smith",
  "phone": "+1987654321"
}

Response: 200 OK

{
  "success": true,
  "message": "Profile updated",
  "user": {
    "id": 1,
    "name": "John Smith",
    "phone": "+1987654321"
  }
}

Change Password

POST /api/user/password
Content-Type: application/json

Request Body:

{
  "currentPassword": "oldpass123",
  "newPassword": "newpass456",
  "confirmPassword": "newpass456"
}

Response: 200 OK

{
  "success": true,
  "message": "Password updated successfully"
}

Errors:

400 Bad Request - Passwords don't match or invalid
401 Unauthorized - Current password incorrect

Get Addresses

GET /api/user/addresses

Response: 200 OK

{
  "addresses": [
    {
      "id": 1,
      "type": "SHIPPING",
      "fullName": "John Doe",
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA",
      "phone": "+1234567890",
      "isDefault": true
    }
  ]
}

Create Address

POST /api/user/addresses
Content-Type: application/json

Request Body:

{
  "type": "SHIPPING",
  "fullName": "John Doe",
  "addressLine1": "123 Main St",
  "addressLine2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "country": "USA",
  "phone": "+1234567890",
  "isDefault": true
}

Response: 201 Created

{
  "success": true,
  "message": "Address created",
  "address": {...}
}

Update Address

PATCH /api/user/addresses/[id]
Content-Type: application/json

Request Body: Same as Create Address

Response: 200 OK

Delete Address

DELETE /api/user/addresses/[id]

Response: 200 OK

Reviews

Get Product Reviews

GET /api/reviews?productId=1&page=1&limit=10

Response: 200 OK

{
  "reviews": [
    {
      "id": 1,
      "rating": 5,
      "comment": "Excellent product!",
      "userId": 2,
      "productId": 1,
      "user": {
        "name": "Jane Doe"
      },
      "createdAt": "2024-11-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "totalPages": 3
  },
  "averageRating": 4.5
}

Create Review

Authentication Required

POST /api/reviews
Content-Type: application/json

Request Body:

{
  "productId": 1,
  "rating": 5,
  "comment": "Great product!"
}

Response: 201 Created

Errors:

400 Bad Request - Invalid rating (must be 1-5)
409 Conflict - User already reviewed this product

Orders

Get User Orders

Authentication Required

GET /api/orders

Response: 200 OK

{
  "orders": [
    {
      "id": 1,
      "orderNumber": "ORD-2024-001",
      "status": "COMPLETED",
      "total": 599.98,
      "items": [...],
      "shippingAddress": {...},
      "createdAt": "2024-11-15T10:00:00.000Z"
    }
  ]
}

Create Order

Authentication Required

POST /api/orders
Content-Type: application/json

Request Body:

{
  "items": [
    {
      "productId": 1,
      "quantity": 2,
      "price": 249.99
    }
  ],
  "shippingAddressId": 1,
  "billingAddressId": 1,
  "paymentMethod": "STRIPE",
  "paymentIntentId": "pi_xxxxx"
}

Response: 201 Created

Admin

Admin Role Required

Dashboard Analytics

GET /api/admin/dashboard

Response: 200 OK

{
  "stats": {
    "totalRevenue": 25000.00,
    "totalOrders": 150,
    "totalCustomers": 75,
    "avgOrderValue": 166.67
  },
  "recentOrders": [...],
  "topProducts": [...],
  "lowStockProducts": [...]
}

List Products (Admin)

GET /api/admin/products?page=1&limit=20&search=tent

Response: 200 OK

{
  "products": [...],
  "pagination": {...}
}

Create Product

POST /api/admin/products
Content-Type: application/json

Request Body:

{
  "title": "New Tent",
  "description": "Description here",
  "price": 299.99,
  "discountedPrice": 249.99,
  "stock": 10,
  "sku": "TENT-001",
  "categoryId": 8
}

Response: 201 Created

Update Product

PUT /api/admin/products/[id]
Content-Type: application/json

Request Body: Same as Create Product

Response: 200 OK

Delete Product

DELETE /api/admin/products/[id]

Response: 200 OK

Upload Product Image

POST /api/admin/products/images
Content-Type: multipart/form-data

Form Data:

file: [image file]
productId: 1
type: PREVIEW | THUMBNAIL

Response: 201 Created

{
  "success": true,
  "message": "Image uploaded",
  "image": {
    "id": 1,
    "url": "/images/products/product-1-bg-1.webp",
    "type": "PREVIEW"
  }
}

Delete Image

DELETE /api/admin/products/images?id=1

Response: 200 OK

Image Audit Report

GET /api/admin/images/audit

Response: 200 OK

{
  "complete": 75,
  "partial": 10,
  "missing": 5,
  "totalProducts": 90,
  "completionPercentage": 83.3
}

Error Handling

Error Response Format

{
  "error": "Error message",
  "details": "Additional details (optional)",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request (validation error)
`401`	Unauthorized (not logged in)
`403`	Forbidden (insufficient permissions)
`404`	Not Found
`409`	Conflict (e.g., duplicate email)
`429`	Too Many Requests (rate limited)
`500`	Internal Server Error

Rate Limiting

Default: 100 requests per 15 minutes per IP
Auth endpoints: 5 requests per 15 minutes
Admin endpoints: 200 requests per 15 minutes

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1637000000

Pagination

All list endpoints support pagination:

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 20, max: 100)

Response includes:

{
  "pagination": {
    "total": 90,
    "page": 1,
    "limit": 20,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false
  }
}

Versioning

Current version: v1

No version prefix in URLs for v1 (default).

Future versions will use: /api/v2/products

Testing

Use these credentials for testing:

Admin:

Email: admin@dcsuniverse.com
Password: admin123

Customer:

Email: demo@dcsuniverse.com
Password: demo123

API Reference

Table of Contents

Authentication

Register User

Login

Logout

Check Session

Products

List Products

Get Product by ID

Categories

List Categories

Get Category by ID

Cart

Get Cart

Add to Cart

Update Cart Item

Remove from Cart

Wishlist

Get Wishlist

Add to Wishlist

Remove from Wishlist

User

Get User Profile

Update Profile

Change Password

Get Addresses

Create Address

Update Address

Delete Address

Reviews

Get Product Reviews

Create Review

Orders

Get User Orders

Create Order

Admin

Dashboard Analytics

List Products (Admin)

Create Product

Update Product

Delete Product

Upload Product Image

Delete Image

Image Audit Report

Error Handling

Error Response Format

HTTP Status Codes

Rate Limiting

Pagination

Versioning

Testing

See Also