orion/docs/api/index.md

# API Overview

The Orion 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://orion.lu/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
```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