Skip to main content

Product Service – API Reference 📦

This document describes the public and admin APIs exposed by the Product Service in ShopVerse.

All APIs are accessed via the API Gateway.
Admin operations are protected using RBAC.

🌐 Base URL​


/api/products

🔐 Authentication & Authorization​

  • Public read APIs are accessible without authentication
  • Admin mutation APIs require ADMIN role
  • JWT is validated at the API Gateway
  • Services rely on gateway-injected headers:
    • X-User-Email
    • X-User-Role

🛍️ Get All Products (Public)​

Fetch all active products with optional filters and pagination.

➤ Endpoint​


GET /api/products

➤ Query Parameters (Optional)​

ParamDescription
pagePage number
sizePage size
categoryFilter by category
brandFilter by brand

➤ Success Response (200 OK)​

{
  "content": [
    {
      "id": "PROD123",
      "name": "Wireless Headphones",
      "price": 2499,
      "stock": 50,
      "brand": "SoundX",
      "category": "Electronics"
    }
  ],
  "totalElements": 120,
  "totalPages": 12
}

🔍 Get Product by ID (Public)​

➤ Endpoint​

GET /api/products/{productId}

➤ Success Response (200 OK)​

{
  "id": "PROD123",
  "name": "Wireless Headphones",
  "description": "Noise cancelling",
  "price": 2499,
  "stock": 50,
  "sku": "SNDX-001",
  "brand": "SoundX",
  "category": "Electronics"
}

➤ Error Responses​

StatusReason
404Product not found

🗂️ Get Categories (Public)​

➤ Endpoint​

GET /api/categories

➤ Success Response (200 OK)​

[
  {
    "id": "CAT01",
    "name": "Electronics"
  },
  {
    "id": "CAT02",
    "name": "Fashion"
  }
]

➕ Create Product (Admin)​

Create a new product.

➤ Endpoint​

POST /api/products

➤ Role Required​

ADMIN

➤ Request Body​

{
  "name": "Bluetooth Speaker",
  "description": "Portable speaker",
  "price": 1999,
  "stock": 100,
  "brand": "BeatBox",
  "categoryId": "CAT01"
}

➤ Success Response (201 CREATED)​

{
  "message": "Product created successfully"
}

✏️ Update Product (Admin)​

➤ Endpoint​

PUT /api/products/{productId}

➤ Role Required​

ADMIN

➤ Request Body​

{
  "price": 1799,
  "stock": 120
}

➤ Success Response (200 OK)​

{
  "message": "Product updated successfully"
}

❌ Delete Product (Admin – Soft Delete)​

Soft delete a product (marks inactive).

➤ Endpoint​

DELETE /api/products/{productId}

➤ Role Required​

ADMIN

➤ Success Response (204 NO CONTENT)​

📦 Bulk Product Creation (Admin)​

Create multiple products in a single request.

➤ Endpoint​

POST /api/products/bulk

➤ Role Required​

ADMIN

➤ Request Body​

[
  {
    "name": "Laptop Bag",
    "price": 1499,
    "stock": 40,
    "brand": "CarryPro",
    "categoryId": "CAT02"
  }
]

➤ Success Response (201 CREATED)​

📡 Events Published​

EventTopicDescription
PRODUCT_CREATEDproduct-eventsProduct added
PRODUCT_UPDATEDproduct-eventsProduct updated
PRODUCT_DELETEDproduct-eventsProduct soft-deleted
PRODUCT_STOCK_UPDATEDproduct-eventsInventory change

🛡️ Authorization Rules Summary​

RoleAllowed Actions
PUBLICView products & categories
ADMINCreate, update, delete products

🔄 Request Flow​

⚠️ Common Errors​

StatusMeaning
400Invalid input
401Unauthorized
403Forbidden
404Product not found
409Conflict

📌 Summary​

The Product API provides:

  • Public product discovery
  • Secure admin-only product management
  • Soft delete & inventory safety
  • Event-driven extensibility

It forms the catalog backbone of the ShopVerse platform.