185 lines
4.8 KiB
Markdown
185 lines
4.8 KiB
Markdown
# 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](http://localhost:8000/docs)** - Interactive API testing interface
|
|
- **[ReDoc](http://localhost:8000/redoc)** - Clean, readable API reference
|
|
- **[OpenAPI Spec](http://localhost:8000/openapi.json)** - 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
|
|
|
|
### Shop API (`/shop/`) - Customer-Facing
|
|
Multi-tenant shop endpoints with automatic vendor 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**: Vendor context automatically injected via `VendorContextMiddleware` using Referer header.
|
|
|
|
### Public API (`/public/`)
|
|
Public endpoints for vendor lookup (no authentication):
|
|
- **Vendor Lookup**: Get vendor by code, subdomain, or ID
|
|
- Returns public vendor information only
|
|
|
|
### Admin API (`/admin/`)
|
|
Admin management endpoints (requires admin authentication):
|
|
- User management (admin only)
|
|
- Vendor management
|
|
- System statistics
|
|
- Configuration management
|
|
- Domain management
|
|
|
|
### Vendor API (`/vendor/`)
|
|
Vendor dashboard endpoints (requires vendor 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
|
|
```json
|
|
{
|
|
"data": {...}, // Main response data
|
|
"message": "Success", // Human-readable message
|
|
"status": 200 // HTTP status code
|
|
}
|
|
```
|
|
|
|
### Error Response Format
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
GET /api/v1/marketplace/product?skip=0&limit=20
|
|
```
|
|
|
|
Response includes pagination metadata:
|
|
```json
|
|
{
|
|
"items": [...],
|
|
"total": 150,
|
|
"skip": 0,
|
|
"limit": 20,
|
|
"has_next": true
|
|
}
|
|
```
|
|
|
|
### Filtering and Searching
|
|
Many endpoints support filtering and search:
|
|
|
|
```bash
|
|
GET /api/v1/marketplace/product?search=laptop&category=electronics&min_price=100
|
|
```
|
|
|
|
### Sorting
|
|
Use the `sort` parameter with field names:
|
|
|
|
```bash
|
|
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](authentication.md)** - Learn about API authentication
|
|
- **[Error Handling](error-handling.md)** - Understanding API errors
|
|
- **[Rate Limiting](rate-limiting.md)** - Rate limiting details
|
|
- **[Interactive Docs](http://localhost:8000/docs)** - Try the API live |