Skip to main content

Notification Service – API Reference 🔔

This document describes the read-only notification APIs exposed by the Notification Service in ShopVerse.

Notifications are generated asynchronously based on domain events and are accessed via the API Gateway.

🌐 Base URL​


/api/notifications

🔐 Authentication & Authorization​

  • JWT is validated at the API Gateway
  • Gateway injects:
    • X-User-Email
    • X-User-Role
  • Users can access only their notifications
  • Admins can access all notifications

📥 Get My Notifications (User)​

Fetch notifications for the authenticated user.

➤ Endpoint​


GET /api/notifications

➤ Query Parameters (Optional)​

ParamDescription
pagePage number
sizePage size
unreadFilter unread notifications

➤ Success Response (200 OK)​

[
  {
    "id": "NTF101",
    "eventType": "ORDER_PLACED",
    "message": "Your order ORD789 has been placed successfully",
    "timestamp": "2026-01-21T12:35:00",
    "read": false
  }
]

✔️ Mark Notification as Read​

Mark a notification as read.

➤ Endpoint​

PUT /api/notifications/{notificationId}/read

➤ Success Response (200 OK)​

{
  "message": "Notification marked as read"
}

👑 Get All Notifications (Admin)​

Fetch all notifications in the system.

➤ Endpoint​

GET /api/notifications/all

➤ Role Required​

ADMIN

➤ Success Response (200 OK)​

[
  {
    "id": "NTF101",
    "userEmail": "user@example.com",
    "eventType": "PAYMENT_SUCCESS",
    "message": "Payment successful for order ORD789",
    "timestamp": "2026-01-21T12:45:00",
    "read": true
  }
]

📡 Events Source​

Notifications are generated from Kafka events published by:

Source ServiceEvent Examples
Auth ServiceUSER_REGISTERED, USER_LOGIN
Order ServiceORDER_PLACED
Payment ServicePAYMENT_SUCCESS
Product ServicePRODUCT_CREATED

🔄 Request Flow​

🛡️ Security Rules Summary​

RoleAccess
CUSTOMEROwn notifications
ADMINAll notifications

Ownership is enforced using X-User-Email.

⚠️ Common Errors​

StatusMeaning
401Unauthorized
403Forbidden
404Notification not found
500Internal server error

📌 Summary​

The Notification API provides:

  • Asynchronous user notifications
  • Secure, role-based access
  • Clean read-only endpoints
  • Event-driven extensibility

It improves user experience without impacting core workflows.