Products API

The Products API provides endpoints for managing products, categories, and variants in the NSGG system.

Categories

List Categories

GET /api/v1/categories/

Query Parameters:

Parameter Type Description
search string Search categories by name or description
ordering string Order results by fields (e.g., name, -created_at)
parent integer Filter by parent category ID

Create Category

POST /api/v1/categories/

Request Body:

{
    "name": "Electronics",
    "description": "Electronic devices and accessories",
    "parent": null
}

Products

List Products

GET /api/v1/products/

Query Parameters:

Parameter Type Description
search string Search products by name, description, or SKU
category integer Filter by category ID
min_price number Filter by minimum price
max_price number Filter by maximum price
in_stock boolean Filter by stock availability
ordering string Order results (e.g., name, -price)

Create Product

POST /api/v1/products/

Request Body:

{
    "name": "Smartphone X",
    "description": "Latest smartphone model",
    "category": 1,
    "price": "999.99",
    "stock": 100,
    "sku": "PHONE-001",
    "is_active": true,
    "variants": [
        {
            "name": "128GB Black",
            "sku": "PHONE-001-128B",
            "price": "999.99",
            "stock": 50
        }
    ]
}

Bulk Create Products

POST /api/v1/products/bulk_create/

Request Body:

[
    {
        "name": "Product 1",
        "category": 1,
        "price": "99.99",
        "stock": 10
    },
    {
        "name": "Product 2",
        "category": 1,
        "price": "149.99",
        "stock": 20
    }
]

Bulk Update Products

PUT /api/v1/products/bulk_update/

Request Body:

[
    {
        "id": 1,
        "price": "89.99",
        "stock": 15
    },
    {
        "id": 2,
        "price": "139.99",
        "stock": 25
    }
]

Product Variants

List Product Variants

GET /api/v1/products/{product_id}/variants/

Create Product Variant

POST /api/v1/products/{product_id}/variants/

Request Body:

{
    "name": "256GB Silver",
    "sku": "PHONE-001-256S",
    "price": "1099.99",
    "stock": 30
}

Caching

  • Category list is cached for 15 minutes
  • Product list is cached for 5 minutes
  • Individual product details are cached for 15 minutes

Rate Limiting

  • Anonymous users: 100 requests per hour
  • Authenticated users: 1000 requests per hour
  • Bulk operations: 100 requests per hour

Error Responses

The API uses standard HTTP status codes and returns error messages in the following format:

{
    "detail": "Error message",
    "code": "error_code"
}

Common error codes:

  • not_found: Resource not found
  • validation_error: Invalid input data
  • permission_denied: Insufficient permissions
  • rate_limit_exceeded: Too many requests