Files

Samir Boulahtit c971674ec2 marketplace refactoring

2025-10-04 13:38:10 +02:00

3.9 KiB

Raw Blame History

API Overview

The Letzshop Import 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://api.letzshop.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

Authentication (`/auth/`)

User registration and login
Token refresh and validation
Password reset workflows

Admin (`/admin/`)

User management (admin only)
System statistics
Configuration management

Products (`/products/`)

MarketplaceProduct CRUD operations
MarketplaceProduct search and filtering
Bulk operations

Shops (`/shops/`)

Shop management
Shop-product associations
Shop statistics

Stock (`/stock/`)

Inventory management
Stock movements
Stock 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

3.9 KiB Raw Blame History