Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
558 lines (442 loc) · 9.43 KB

API_DOCUMENTATION.md

File metadata and controls

558 lines (442 loc) · 9.43 KB

4Seasons Real Estate API Documentation

Overview

This document provides comprehensive documentation for the 4Seasons Real Estate application API. The API is built with Express.js 4.21.2, TypeScript 5.6.3, and follows REST conventions with comprehensive security middleware.

Base URL: https://your-domain.com/api

Authentication

The API supports dual authentication methods:

  • Session-based: For web application use
  • JWT-based: For API access and mobile applications

Authentication Headers

Authorization: Bearer <jwt_token>
Content-Type: application/json
X-CSRF-Token: <csrf_token>  // Required for POST/PUT/DELETE

Rate Limiting

  • General API: 100 requests per 15 minutes
  • Auth endpoints: 5 requests per 15 minutes
  • Contact forms: 3 submissions per hour

Response Format

All API responses follow this structure:

Success Response:

{
  "success": true,
  "data": {},
  "message": "Operation completed successfully"
}

Error Response:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

🔐 Authentication Routes (/api/auth)

POST /api/auth/register

Register a new user account.

Rate Limit: 5 requests/15 min

Request Body:

{
  "username": "string (required, 2-50 chars)",
  "password": "string (required, 8+ chars, uppercase, lowercase, number, special char)",
  "email": "string (optional, valid email)"
}

Response:

{
  "success": true,
  "user": {
    "id": "uuid",
    "username": "string",
    "email": "string",
    "role": "user",
    "createdAt": "timestamp"
  },
  "token": "jwt_token"
}

Error Codes:

  • 409 - Username already exists
  • 400 - Invalid password requirements
  • 400 - Validation errors

POST /api/auth/login

Authenticate user credentials.

Rate Limit: 5 requests/15 min

Request Body:

{
  "username": "string (required)",
  "password": "string (required)"
}

Response:

{
  "success": true,
  "user": {
    "id": "uuid",
    "username": "string",
    "role": "string",
    "lastLoginAt": "timestamp"
  },
  "token": "jwt_token"
}

POST /api/auth/logout

Logout current user session.

Authentication: Required

Response:

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

📧 Forms Routes (/api/forms)

POST /api/forms/contact

Submit contact form inquiry.

Rate Limit: 3 requests/hour

Request Body:

{
  "name": "string (required, 2-100 chars)",
  "email": "string (required, valid email)",
  "phone": "string (optional, valid phone)",
  "message": "string (required, 10-2000 chars)",
  "subject": "string (optional, max 200 chars)",
  "propertyInterest": "string (optional, max 200 chars)",
  "honeypot": "string (should be empty - anti-spam)"
}

Response:

{
  "success": true,
  "message": "Thank you for your inquiry! We'll be in touch soon.",
  "inquiryId": "uuid"
}

POST /api/forms/property-inquiry

Submit property-specific inquiry.

Request Body:

{
  "name": "string (required)",
  "email": "string (required)",
  "phone": "string (optional)",
  "message": "string (required)",
  "propertyId": "string (required)",
  "propertyAddress": "string (optional)",
  "inquiryType": "string (buying|selling|renting)"
}

🏠 MLS Routes (/api/mls)

GET /api/mls/properties

Retrieve property listings from MLS.

Query Parameters:

?city=string
&priceMin=number
&priceMax=number
&beds=number
&baths=number
&limit=number (default: 50, max: 100)
&offset=number (default: 0)

Response:

{
  "success": true,
  "data": {
    "properties": [
      {
        "mlsId": "string",
        "address": "string",
        "city": "string",
        "price": "number",
        "beds": "number",
        "baths": "number",
        "sqft": "number",
        "images": ["string"],
        "description": "string",
        "listingDate": "timestamp"
      }
    ],
    "total": "number",
    "hasMore": "boolean"
  }
}

GET /api/mls/property/:mlsId

Get detailed property information.

Response:

{
  "success": true,
  "data": {
    "property": {
      "mlsId": "string",
      "fullDetails": "object"
    }
  }
}

🛡️ Security Routes (/api/security)

POST /api/security/scan

Run security vulnerability scan.

Authentication: Admin required

Response:

{
  "success": true,
  "data": {
    "scanId": "uuid",
    "vulnerabilities": [
      {
        "type": "string",
        "severity": "high|medium|low",
        "description": "string",
        "recommendation": "string"
      }
    ],
    "score": "number (0-100)"
  }
}

GET /api/security/audit-logs

Retrieve security audit logs.

Authentication: Admin required

Query Parameters:

?limit=number (default: 100)
&offset=number
&startDate=timestamp
&endDate=timestamp
&action=string
&userId=uuid

👤 Admin Routes (/api/admin)

GET /api/admin/users

List all users.

Authentication: Admin required

Response:

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "uuid",
        "username": "string",
        "email": "string",
        "role": "string",
        "isActive": "boolean",
        "createdAt": "timestamp",
        "lastLoginAt": "timestamp"
      }
    ]
  }
}

PUT /api/admin/users/:userId/role

Update user role.

Authentication: Admin required

Request Body:

{
  "role": "admin|moderator|user|guest"
}

DELETE /api/admin/users/:userId

Deactivate user account.

Authentication: Admin required

📊 Performance Routes (/api/performance)

GET /api/performance/metrics

Get application performance metrics.

Authentication: Admin required

Response:

{
  "success": true,
  "data": {
    "responseTime": {
      "average": "number",
      "p95": "number",
      "p99": "number"
    },
    "memoryUsage": {
      "used": "number",
      "total": "number",
      "percentage": "number"
    },
    "requestCount": {
      "total": "number",
      "perMinute": "number"
    },
    "errorRate": "number"
  }
}

POST /api/performance/clear-cache

Clear application cache.

Authentication: Admin required

💾 Backup Routes (/api/backup)

POST /api/backup/create

Create database backup.

Authentication: Admin required

Request Body:

{
  "type": "full|incremental",
  "description": "string (optional)"
}

GET /api/backup/list

List available backups.

Authentication: Admin required

POST /api/backup/restore/:backupId

Restore from backup.

Authentication: Admin required

🗄️ Cache Routes (/api/cache)

DELETE /api/cache/clear

Clear all application cache.

Authentication: Admin required

DELETE /api/cache/clear/:key

Clear specific cache key.

Authentication: Admin required

📤 Upload Routes (/api/upload)

POST /api/upload/image

Upload image file.

Authentication: Required

Content-Type: multipart/form-data

Request:

  • File field: image
  • Max size: 50MB
  • Allowed types: JPG, PNG, GIF, WebP

Response:

{
  "success": true,
  "data": {
    "filename": "string",
    "originalName": "string",
    "url": "string",
    "size": "number",
    "dimensions": {
      "width": "number",
      "height": "number"
    }
  }
}

📧 Email Test Routes (/api/email-test)

POST /api/email-test/send

Send test email.

Authentication: Admin required

Request Body:

{
  "to": "string (email)",
  "subject": "string",
  "message": "string"
}

Security Features

CSRF Protection

All state-changing operations (POST, PUT, DELETE) require CSRF token:

  1. Get token: GET /api/csrf-token
  2. Include in header: X-CSRF-Token: <token>

Input Validation

  • All inputs validated with express-validator 7.2.1
  • XSS protection with DOMPurify 2.27.0
  • SQL injection prevention via Drizzle ORM parameterized queries

Security Headers

  • Helmet.js 8.1.0 security headers
  • CORS 2.8.5 with whitelisted origins
  • Content Security Policy
  • X-Frame-Options: SAMEORIGIN

Rate Limiting

  • Express-rate-limit 8.0.1
  • Redis-backed rate limiting
  • Per-endpoint limits

Error Handling

HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 429 - Too Many Requests
  • 500 - Internal Server Error

Common Error Responses

Validation Error:

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "field": "error message"
  }
}

Authentication Error:

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

Rate Limit Error:

{
  "success": false,
  "error": "Too many requests",
  "retryAfter": "number (seconds)"
}

Environment Configuration

Required environment variables for API functionality:

# Core
NODE_ENV=production
PORT=5000
DATABASE_URL=postgresql://...
JWT_SECRET=your-jwt-secret
SESSION_SECRET=your-session-secret

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email
SMTP_PASS=your-password

# Security
ALLOWED_ORIGINS=https://yourdomain.com
CSRF_SECRET=your-csrf-secret

# Redis (optional, for caching)
REDIS_URL=redis://localhost:6379

Last Updated: 2026-05-28 API Version: 1.0.0 Technology Stack: Express.js 4.21.2, TypeScript 5.6.3, Node.js 20.x