REST API Advanced - Complete API Documentation

Overview
Getting Started
Authentication
Rate Limiting
Error Handling
API Endpoints
- Authentication
- Users
- Products
- Orders
- Health
Data Models
Example Workflows
Best Practices

Overview

The Advanced REST API is a production-ready e-commerce API built with Node.js, Express, and MongoDB. It features:

JWT-based authentication with refresh tokens
Role-based access control (RBAC)
Comprehensive input validation
Rate limiting and security headers
Redis caching for performance
Detailed error handling
API documentation with Swagger
Health checks and monitoring
Automated testing suite

Base URL

Development: http://localhost:3000/api
Production: https://api.example.com/api

API Version

Current version: 1.0.0

Getting Started

Prerequisites

Node.js >= 16.0.0
MongoDB >= 4.4
Redis >= 6.0 (optional, for caching)

Quick Start

Clone the repository
Install dependencies: npm install
Set up environment variables (see .env.example)
Start MongoDB and Redis
Run database seeders: npm run seed
Start the server: npm run dev

Environment Variables

env

# Server Configuration
PORT=3000
NODE_ENV=development
API_URL=http://localhost:3000

# Database
MONGODB_URI=mongodb://localhost:27017/rest-api-advanced

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRE=7d
JWT_REFRESH_EXPIRE=30d
ROTATE_REFRESH_TOKENS=true

# Security
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
BCRYPT_ROUNDS=10

# Email (for production)
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
[email protected]
EMAIL_PASS=your-email-password
[email protected]

Authentication

The API uses JWT (JSON Web Tokens) for authentication with support for refresh tokens.

Authentication Flow

Register/Login: User provides credentials and receives access and refresh tokens
Access Protected Routes: Include the access token in the Authorization header
Token Refresh: When access token expires, use refresh token to get a new one
Logout: Blacklist the current token

Token Format

Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Token Expiration

Access Token: 7 days (configurable)
Refresh Token: 30 days (configurable)

Password Requirements

Minimum 6 characters
Recommended: Include uppercase, lowercase, numbers, and special characters

Rate Limiting

The API implements rate limiting to prevent abuse:

General Endpoints

Limit: 100 requests per 15 minutes per IP
Headers:
- X-RateLimit-Limit: Total requests allowed
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Reset timestamp

Authentication Endpoints

Limit: 5 requests per 15 minutes per IP
Note: Only failed attempts count against the limit

Rate Limit Response

When rate limit is exceeded:

json

{
  "success": false,
  "message": "Too many requests from this IP, please try again later.",
  "error": {
    "statusCode": 429,
    "message": "Rate limit exceeded"
  }
}

Error Handling

The API uses consistent error responses across all endpoints.

Error Response Format

json

{
  "success": false,
  "message": "Human-readable error message",
  "error": {
    "statusCode": 400,
    "message": "Detailed error description"
  }
}

Validation Error Format

json

{
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "password",
      "message": "Password must be at least 6 characters"
    }
  ]
}

Common Error Codes

400 - Bad Request (validation errors)
401 - Unauthorized (missing/invalid token)
403 - Forbidden (insufficient permissions)
404 - Not Found
409 - Conflict (duplicate resource)
429 - Too Many Requests (rate limit)
500 - Internal Server Error

API Endpoints

Authentication Endpoints

Register User

http

POST /api/auth/register

Create a new user account.

Request Body:

json

{
  "email": "[email protected]",
  "password": "SecurePass123!",
  "name": "John Doe"
}

Response (201):

json

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user",
    "isEmailVerified": false,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Login User

http

POST /api/auth/login

Authenticate user and receive tokens.

Request Body:

json

{
  "email": "[email protected]",
  "password": "SecurePass123!"
}

Response (200):

json

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user",
    "lastLogin": "2024-01-01T00:00:00.000Z"
  }
}

Refresh Token

http

POST /api/auth/refresh

Get new access token using refresh token.

Request Body:

json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200):

json

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Logout

http

POST /api/auth/logout

Logout and blacklist current token.

Headers:

Authorization: Bearer <token>

Response (200):

json

{
  "success": true,
  "message": "Logged out successfully"
}

Get Current User

http

GET /api/auth/me

Get authenticated user details.

Headers:

Authorization: Bearer <token>

Response (200):

json

{
  "success": true,
  "data": {
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "user",
      "isEmailVerified": true,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

Forgot Password

http

POST /api/auth/forgot-password

Request password reset email.

Request Body:

json

{
  "email": "[email protected]"
}

Response (200):

json

{
  "success": true,
  "message": "Password reset email sent"
}

Reset Password

http

POST /api/auth/reset-password

Reset password using token from email.

Request Body:

json

{
  "token": "reset-token-from-email",
  "password": "NewSecurePass123!"
}

Response (200):

json

{
  "success": true,
  "message": "Password reset successful"
}

Verify Email

http

GET /api/auth/verify-email/:token

Verify email address using token from email.

Response (200):

json

{
  "success": true,
  "message": "Email verified successfully"
}

Check Password Strength

http

POST /api/auth/check-password

Check password strength without creating account.

Request Body:

json

{
  "password": "MyStr0ng!Pass"
}

Response (200):

json

{
  "success": true,
  "data": {
    "strength": {
      "isValid": true,
      "score": 5,
      "level": "strong",
      "feedback": []
    }
  }
}

Product Endpoints

Get All Products

http

GET /api/products

Get paginated list of products with filtering and sorting.

Query Parameters:

page (default: 1) - Page number
limit (default: 20) - Items per page
search - Search by name or description
category - Filter by category
minPrice - Minimum price filter
maxPrice - Maximum price filter
sort - Sort field (price, -price, name, -name, createdAt, -createdAt)
inStock - Filter by stock availability (true/false)

Response (200):

json

{
  "success": true,
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Laptop",
      "description": "High-performance laptop",
      "price": 999.99,
      "category": "Electronics",
      "sku": "LAP001",
      "stock": 10,
      "images": ["https://example.com/image1.jpg"],
      "tags": ["new", "featured"],
      "averageRating": 4.5,
      "reviewCount": 25,
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Get Product by ID

http

GET /api/products/:id

Get detailed product information.

Response (200):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Laptop",
    "description": "High-performance laptop with latest specs",
    "price": 999.99,
    "category": "Electronics",
    "sku": "LAP001",
    "stock": 10,
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "tags": ["new", "featured"],
    "specifications": {
      "brand": "TechBrand",
      "model": "TB-2024",
      "weight": "1.5kg",
      "dimensions": "35x25x2cm"
    },
    "reviews": [
      {
        "id": "507f1f77bcf86cd799439012",
        "user": "507f1f77bcf86cd799439013",
        "rating": 5,
        "title": "Excellent product!",
        "comment": "Very satisfied with this laptop.",
        "helpfulCount": 10,
        "createdAt": "2024-01-02T00:00:00.000Z"
      }
    ],
    "averageRating": 4.5,
    "reviewCount": 25,
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Create Product (Admin)

http

POST /api/products

Create a new product.

Headers:

Authorization: Bearer <admin-token>

Request Body:

json

{
  "name": "New Product",
  "description": "Product description",
  "price": 149.99,
  "category": "Electronics",
  "sku": "NEW001",
  "stock": 20,
  "tags": ["new"],
  "specifications": {
    "weight": "500g",
    "dimensions": "10x10x5cm"
  }
}

Response (201):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439014",
    "name": "New Product",
    "price": 149.99,
    "category": "Electronics",
    "sku": "NEW001",
    "stock": 20,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Update Product (Admin)

http

PUT /api/products/:id

Update product details.

Headers:

Authorization: Bearer <admin-token>

Request Body:

json

{
  "name": "Updated Product Name",
  "price": 129.99,
  "stock": 15
}

Response (200):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Updated Product Name",
    "price": 129.99,
    "stock": 15,
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Delete Product (Admin)

http

DELETE /api/products/:id

Delete a product.

Headers:

Authorization: Bearer <admin-token>

Response (200):

json

{
  "success": true,
  "message": "Product deleted successfully"
}

Add Product Review

http

POST /api/products/:id/reviews

Add a review to a product.

Headers:

Authorization: Bearer <token>

Request Body:

json

{
  "rating": 5,
  "title": "Excellent product!",
  "comment": "Very satisfied with this purchase."
}

Response (201):

json

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "507f1f77bcf86cd799439015",
        "user": "507f1f77bcf86cd799439013",
        "rating": 5,
        "title": "Excellent product!",
        "comment": "Very satisfied with this purchase.",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "averageRating": 5,
    "reviewCount": 1
  }
}

Update Inventory (Admin)

http

PUT /api/products/:id/inventory

Update product inventory.

Headers:

Authorization: Bearer <admin-token>

Request Body:

json

{
  "stock": 50,
  "operation": "set" // "set", "increment", "decrement"
}

Response (200):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "stock": 50,
    "lastStockUpdate": "2024-01-01T00:00:00.000Z"
  }
}

Order Endpoints

Create Order

http

POST /api/orders

Create a new order.

Headers:

Authorization: Bearer <token>

Request Body:

json

{
  "items": [
    {
      "product": "507f1f77bcf86cd799439011",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "name": "John Doe",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "paymentMethod": "credit_card",
  "notes": "Please deliver between 9 AM - 5 PM"
}

Response (201):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439016",
    "orderNumber": "ORD-2024-0001",
    "items": [
      {
        "product": "507f1f77bcf86cd799439011",
        "quantity": 2,
        "price": 99.99,
        "subtotal": 199.98
      }
    ],
    "subtotal": 199.98,
    "tax": 20.00,
    "shipping": 10.00,
    "totalAmount": 229.98,
    "status": "pending",
    "paymentStatus": "pending",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Get User Orders

http

GET /api/orders

Get authenticated user's orders.

Headers:

Authorization: Bearer <token>

Query Parameters:

page (default: 1)
limit (default: 20)
status - Filter by order status
sort - Sort orders

Response (200):

json

{
  "success": true,
  "data": [
    {
      "id": "507f1f77bcf86cd799439016",
      "orderNumber": "ORD-2024-0001",
      "totalAmount": 229.98,
      "status": "pending",
      "paymentStatus": "completed",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 10,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Get Order Details

http

GET /api/orders/:id

Get detailed order information.

Headers:

Authorization: Bearer <token>

Response (200):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439016",
    "orderNumber": "ORD-2024-0001",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "items": [
      {
        "product": {
          "id": "507f1f77bcf86cd799439011",
          "name": "Laptop",
          "price": 99.99
        },
        "quantity": 2,
        "price": 99.99,
        "subtotal": 199.98
      }
    ],
    "subtotal": 199.98,
    "tax": 20.00,
    "shipping": 10.00,
    "totalAmount": 229.98,
    "status": "pending",
    "paymentStatus": "completed",
    "paymentMethod": "credit_card",
    "shippingAddress": {
      "name": "John Doe",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA"
    },
    "tracking": null,
    "statusHistory": [
      {
        "status": "pending",
        "timestamp": "2024-01-01T00:00:00.000Z"
      }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Cancel Order

http

DELETE /api/orders/:id

Cancel an order (only pending/processing orders).

Headers:

Authorization: Bearer <token>

Response (200):

json

{
  "success": true,
  "message": "Order cancelled successfully"
}

Update Order Status (Admin)

http

PUT /api/orders/:id/status

Update order status.

Headers:

Authorization: Bearer <admin-token>

Request Body:

json

{
  "status": "processing" // "pending", "processing", "shipped", "delivered", "cancelled"
}

Response (200):

json

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439016",
    "status": "processing",
    "statusHistory": [
      {
        "status": "pending",
        "timestamp": "2024-01-01T00:00:00.000Z"
      },
      {
        "status": "processing",
        "timestamp": "2024-01-01T01:00:00.000Z",
        "updatedBy": "507f1f77bcf86cd799439017"
      }
    ]
  }
}

Add Tracking Information (Admin)

http

POST /api/orders/:id/tracking

Add shipping tracking information.

Headers:

Authorization: Bearer <admin-token>

Request Body:

json

{
  "carrier": "FedEx",
  "trackingNumber": "1234567890",
  "estimatedDelivery": "2024-01-20"
}

Response (200):

json

{
  "success": true,
  "data": {
    "tracking": {
      "carrier": "FedEx",
      "trackingNumber": "1234567890",
      "estimatedDelivery": "2024-01-20"
    }
  }
}

Health Endpoints

Health Check

http

GET /api/health

Basic health check.

Response (200):

json

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 3600,
  "environment": "development"
}

Readiness Check

http

GET /api/health/ready

Check if all services are ready.

Response (200):

json

{
  "status": "ready",
  "checks": {
    "database": "connected",
    "redis": "connected"
  }
}

Liveness Check

http

GET /api/health/live

Check if the service is alive.

Response (200):

json

{
  "status": "alive",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Data Models

User Model

javascript

{
  _id: ObjectId,
  email: String (unique, required),
  password: String (hashed, required),
  name: String (required),
  role: String (enum: ['user', 'admin'], default: 'user'),
  isActive: Boolean (default: true),
  isEmailVerified: Boolean (default: false),
  emailVerificationToken: String,
  passwordResetToken: String,
  passwordResetExpires: Date,
  loginAttempts: Number (default: 0),
  lockUntil: Date,
  lastLogin: Date,
  createdAt: Date,
  updatedAt: Date
}

Product Model

javascript

{
  _id: ObjectId,
  name: String (required),
  description: String,
  price: Number (required, min: 0),
  category: String (required),
  sku: String (unique, required),
  stock: Number (default: 0, min: 0),
  images: [String],
  tags: [String],
  specifications: Object,
  reviews: [{
    user: ObjectId (ref: 'User'),
    rating: Number (1-5),
    title: String,
    comment: String,
    helpfulCount: Number (default: 0),
    createdAt: Date
  }],
  averageRating: Number (default: 0),
  reviewCount: Number (default: 0),
  isActive: Boolean (default: true),
  createdAt: Date,
  updatedAt: Date
}

Order Model

javascript

{
  _id: ObjectId,
  orderNumber: String (unique, required),
  user: ObjectId (ref: 'User', required),
  items: [{
    product: ObjectId (ref: 'Product'),
    quantity: Number (min: 1),
    price: Number,
    subtotal: Number
  }],
  subtotal: Number (required),
  tax: Number (default: 0),
  shipping: Number (default: 0),
  totalAmount: Number (required),
  status: String (enum: ['pending', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded']),
  paymentStatus: String (enum: ['pending', 'completed', 'failed', 'refunded']),
  paymentMethod: String (enum: ['credit_card', 'debit_card', 'paypal', 'stripe']),
  paymentDetails: Object,
  shippingAddress: {
    name: String,
    street: String,
    city: String,
    state: String,
    zipCode: String,
    country: String
  },
  tracking: {
    carrier: String,
    trackingNumber: String,
    estimatedDelivery: Date
  },
  notes: String,
  statusHistory: [{
    status: String,
    timestamp: Date,
    updatedBy: ObjectId (ref: 'User')
  }],
  refunds: [{
    amount: Number,
    reason: String,
    processedAt: Date,
    processedBy: ObjectId (ref: 'User')
  }],
  createdAt: Date,
  updatedAt: Date
}

Example Workflows

Complete Purchase Flow

Browse Products

http

GET /api/products?category=Electronics&sort=-rating

View Product Details

http

GET /api/products/507f1f77bcf86cd799439011

Register/Login

http

POST /api/auth/register
{
  "email": "[email protected]",
  "password": "SecurePass123!",
  "name": "John Doe"
}

Add Review (optional)

http

POST /api/products/507f1f77bcf86cd799439011/reviews
{
  "rating": 5,
  "comment": "Great product!"
}

Create Order

http

POST /api/orders
{
  "items": [
    {
      "product": "507f1f77bcf86cd799439011",
      "quantity": 1
    }
  ],
  "shippingAddress": {
    "name": "John Doe",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "paymentMethod": "credit_card"
}

Track Order

http

GET /api/orders/507f1f77bcf86cd799439016

Admin Product Management

Login as Admin

http

POST /api/auth/login
{
  "email": "[email protected]",
  "password": "AdminPass123!"
}

Create Product

http

POST /api/products
{
  "name": "New Laptop",
  "description": "Latest model laptop",
  "price": 1299.99,
  "category": "Electronics",
  "sku": "LAP002",
  "stock": 25
}

Update Inventory

http

PUT /api/products/507f1f77bcf86cd799439011/inventory
{
  "stock": 50,
  "operation": "set"
}

Process Orders

http

GET /api/orders/admin/all?status=pending

PUT /api/orders/507f1f77bcf86cd799439016/status
{
  "status": "processing"
}

POST /api/orders/507f1f77bcf86cd799439016/tracking
{
  "carrier": "FedEx",
  "trackingNumber": "1234567890"
}

Best Practices

Security

Always use HTTPS in production
Store sensitive data in environment variables
Implement proper CORS configuration
Use strong JWT secrets (minimum 32 characters)
Enable rate limiting on all endpoints
Validate and sanitize all user inputs
Keep dependencies updated

Performance

Use pagination for list endpoints
Implement caching with Redis
Create database indexes for frequently queried fields
Use projection to limit returned fields
Compress responses with gzip

API Usage

Include proper error handling in your client
Implement token refresh logic
Use appropriate HTTP methods
Include meaningful request IDs for debugging
Handle rate limiting gracefully

Testing

Test both success and error scenarios
Include edge cases in your tests
Test with different user roles
Verify data validation rules
Test concurrent requests

Support

For API support, please contact:

Email: [email protected]
Documentation: https://api.example.com/docs
Status Page: https://status.example.com

Changelog

Version 1.0.0 (Current)

Initial release
Complete authentication system
Product catalog with reviews
Order management
Admin functionality
Health checks
Rate limiting
Comprehensive validation

REST API Advanced - Complete API Documentation

REST API Advanced - Complete API Documentation

Table of Contents

Overview

Base URL

API Version

Getting Started

Prerequisites

Quick Start

Environment Variables

Authentication

Authentication Flow

Token Format

Token Expiration

Password Requirements

Rate Limiting

General Endpoints

Authentication Endpoints

Rate Limit Response

Error Handling

Error Response Format

Validation Error Format

Common Error Codes

API Endpoints

Authentication Endpoints

Register User

Login User

Refresh Token

Logout

Get Current User

Forgot Password

Reset Password

Verify Email

Check Password Strength

Product Endpoints

Get All Products

Get Product by ID

Create Product (Admin)

Update Product (Admin)

Delete Product (Admin)

Add Product Review

Update Inventory (Admin)

Order Endpoints

Create Order

Get User Orders

Get Order Details

Cancel Order

Update Order Status (Admin)

Add Tracking Information (Admin)

Health Endpoints

Health Check

Readiness Check

Liveness Check

Data Models

User Model

Product Model

Order Model

Example Workflows

Complete Purchase Flow

Admin Product Management

Best Practices

Security

Performance

API Usage

Testing

Support

Changelog

Version 1.0.0 (Current)