orion/docs/api/index.md

API Overview

The Wizamart API provides comprehensive endpoints for managing products, shops, users, and marketplace imports. This section provides high-level guidance and concepts for working with our API.

Interactive Documentation

For hands-on API exploration and testing, use our interactive documentation:

!!! tip "Live API Documentation" - Swagger UI - Interactive API testing interface - ReDoc - Clean, readable API reference - OpenAPI Spec - Machine-readable API specification

API Structure

Base URL

Production: https://wizamart.com/api/v1
Development: http://localhost:8000/api/v1

API Versioning

All API endpoints are versioned using URL path versioning:

• Current version: v1
• All endpoints are prefixed with /api/v1/

Endpoint Categories

Storefront API (/storefront/) - Customer-Facing

Multi-tenant storefront endpoints with automatic store context from middleware:

• Products: Browse catalog, search, product details
• Cart: Shopping cart operations (session-based)
• Orders: Order placement and history (authenticated)
• Authentication: Customer login, registration, password reset
• Content Pages: CMS pages (about, FAQ, etc.)

Note: Store context automatically injected via StoreContextMiddleware using Referer header.

Public API (/public/)

Public endpoints for store lookup (no authentication):

• Store Lookup: Get store by code, subdomain, or ID
• Returns public store information only

Admin API (/admin/)

Admin management endpoints (requires admin authentication):

• User management (admin only)
• Store management
• System statistics
• Configuration management
• Domain management

Store API (/store/)

Store dashboard endpoints (requires store authentication):

• Product management
• Order management
• Customer management
• Store settings
• Analytics and reporting

Products (/products/)

• MarketplaceProduct CRUD operations
• MarketplaceProduct search and filtering
• Bulk operations

Shops (/shops/)

• Shop management
• Shop-product associations
• Shop statistics

Inventory (/inventory/)

• Inventory management
• Inventory movements
• Inventory reporting

Marketplace (/marketplace/)

• Import job management
• CSV file processing
• Import status tracking

Statistics (/stats/)

• System-wide statistics
• User activity metrics
• Import performance data

Request/Response Format

Content Type

All API endpoints use JSON for request and response bodies:

Content-Type: application/json

Standard Response Format

{
  "data": {...},           // Main response data
  "message": "Success",    // Human-readable message
  "status": 200           // HTTP status code
}

Error Response Format

{
  "detail": "Error description",
  "type": "validation_error",
  "errors": [             // Field-specific errors (if applicable)
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Common Patterns

Pagination

Most list endpoints support pagination:

GET /api/v1/marketplace/product?skip=0&limit=20

Response includes pagination metadata:

{
  "items": [...],
  "total": 150,
  "skip": 0,
  "limit": 20,
  "has_next": true
}

Filtering and Searching

Many endpoints support filtering and search:

GET /api/v1/marketplace/product?search=laptop&category=electronics&min_price=100

Sorting

Use the sort parameter with field names:

GET /api/v1/marketplace/product?sort=name&order=desc

Status Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no content returned
400	Bad Request	Invalid request data
401	Unauthorized	Authentication required
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Rate Limiting

API endpoints are rate limited to ensure fair usage:

• Default limit: 100 requests per minute per IP
• Authenticated users: 1000 requests per minute
• Admin users: 5000 requests per minute

Rate limit headers are included in responses:

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

Next Steps

• Authentication Guide - Learn about API authentication
• Error Handling - Understanding API errors
• Rate Limiting - Rate limiting details
• Interactive Docs - Try the API live