Skip to main content

Recommendation Service – API Reference 🤖

This document describes the recommendation APIs exposed by the Recommendation Service in ShopVerse.

The service provides personalized product recommendations based on user interactions, processed asynchronously using Kafka.

🌐 Base URL​


/api/recommendations

🔐 Authentication & Authorization​

  • JWT is validated at the API Gateway
  • Gateway injects:
    • X-User-Email
    • X-User-Role
  • Only authenticated users with role CUSTOMER can access recommendations
  • Admin access is not applicable

🎯 Get Recommendations (Customer)​

Fetch recommended products for the authenticated user.

➤ Endpoint​


GET /api/recommendations

➤ Query Parameters (Optional)​

ParamDescription
limitNumber of recommendations (default: 10)

➤ Success Response (200 OK)​

[
  {
    "productId": "PROD123",
    "score": 12.5,
    "source": "PERSONAL"
  },
  {
    "productId": "PROD456",
    "score": 9.0,
    "source": "POPULAR"
  }
]

🧠 Recommendation Logic (High-Level)​

  • If user interaction data exists → Personalized recommendations
  • If insufficient data → Popular products fallback
  • Recommendations are read-only
  • Scores are calculated using weighted interaction events

🔄 Request Flow​

📡 Data Source​

Recommendations are generated from Kafka events:

Event TypeSource
VIEW_PRODUCTProduct Service
ADD_TO_CARTOrder Service
ORDER_PLACEDOrder Service

These events are processed asynchronously and stored in MongoDB.

🛡️ Security Rules​

RoleAccess
CUSTOMERFetch own recommendations
ADMIN❌ Not allowed

⚠️ Common Errors​

StatusMeaning
401Unauthorized
403Forbidden
500Recommendation generation failure

📌 Summary​

The Recommendation API provides:

  • Personalized product discovery
  • Event-driven scalability
  • Clean read-only access
  • Secure, customer-only endpoints

It enhances user engagement without affecting core transactions.