SERVICE_CATALOGUE_API_QUICK_REF.md

Service Catalogue API - Quick Reference (SPA-MS)

Overview

Customer-facing API for listing and viewing service catalogue in SPA microservice.

Data Source: scm_service_catalogue (MongoDB)
Base Path: /customer/services
Authentication: Optional (depends on deployment)

Endpoints

1. List Services (with Projection Support)

POST /customer/services/list

Request Body:

{
  "category": "Hair Services",
  "status": "active",
  "limit": 20,
  "offset": 0,
  "projection_list": ["service_id", "name", "price", "duration_mins"]
}

Response (with projection):

[
  {
    "service_id": "uuid",
    "name": "Hair Cut",
    "price": 500.00,
    "duration_mins": 30
  }
]

Response (without projection):

{
  "services": [
    {
      "service_id": "uuid",
      "merchant_id": "merchant_123",
      "name": "Hair Cut",
      "code": "SVC001",
      "category": {
        "id": "cat_hair",
        "name": "Hair Services"
      },
      "description": "Professional hair cutting service",
      "duration_mins": 30,
      "price": 500.00,
      "currency": "INR",
      "gst_rate": 18.0,
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 15
  }
}

Projection Fields:

• service_id - Service UUID
• merchant_id - Merchant UUID
• name - Service name
• code - Service code
• category - Category object
• description - Service description
• duration_mins - Duration in minutes
• price - Service price
• currency - Currency code
• gst_rate - GST rate percentage
• status - Service status

---

2. Get Service by ID

GET /customer/services/{service_id}

Response: CustomerServiceResponse

---

3. Legacy GET List (Deprecated)

GET /customer/services?category=Hair%20Services&status=active&limit=20&offset=0

Note: Use POST /list instead for projection support.

---

Request Schema

ServiceListRequest

{
  "category": "string (optional)",
  "status": "active|inactive|archived (optional)",
  "limit": 20,
  "offset": 0,
  "projection_list": ["field1", "field2"]
}

---

Response Schema

CustomerServiceResponse

{
  "service_id": "uuid",
  "merchant_id": "uuid",
  "name": "Hair Cut",
  "code": "SVC001",
  "category": {
    "id": "cat_123",
    "name": "Hair Services"
  },
  "description": "Professional hair cutting service",
  "duration_mins": 30,
  "price": 500.00,
  "currency": "INR",
  "gst_rate": 18.0,
  "status": "active"
}

---

Example Usage

List All Active Services

curl -X POST "http://localhost:8000/customer/services/list" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "limit": 20,
    "offset": 0
  }'

List Services by Category

curl -X POST "http://localhost:8000/customer/services/list" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "Hair Services",
    "status": "active",
    "limit": 20,
    "offset": 0
  }'

List Services with Projection (Performance Optimized)

curl -X POST "http://localhost:8000/customer/services/list" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "Hair Services",
    "status": "active",
    "limit": 20,
    "offset": 0,
    "projection_list": ["service_id", "name", "price", "duration_mins"]
  }'

Get Service Details

curl -X GET "http://localhost:8000/customer/services/{service_id}"

---

Filters

category

Filter services by category name (case-insensitive).

Example:

{
  "category": "Hair Services"
}

status

Filter services by status.

Valid Values: active, inactive, archived

Example:

{
  "status": "active"
}

---

Pagination

Use limit and offset for pagination:

{
  "limit": 20,
  "offset": 0
}

Rules:

• limit: 1-100 (default: 20)
• offset: >= 0 (default: 0)

---

Projection List Benefits

Using projection_list reduces payload size significantly:

Without Projection (Full Response):

{
  "service_id": "uuid",
  "merchant_id": "merchant_123",
  "name": "Hair Cut",
  "code": "SVC001",
  "category": {"id": "cat_hair", "name": "Hair Services"},
  "description": "Professional hair cutting service",
  "duration_mins": 30,
  "price": 500.00,
  "currency": "INR",
  "gst_rate": 18.0,
  "status": "active"
}

With Projection (Minimal Response):

{
  "service_id": "uuid",
  "name": "Hair Cut",
  "price": 500.00,
  "duration_mins": 30
}

Payload Reduction: ~70% smaller

---

Error Responses

404 Not Found

{
  "detail": "Service with ID 'xyz' not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "status"],
      "msg": "Status must be one of: active, inactive, archived",
      "type": "value_error"
    }
  ]
}

500 Internal Server Error

{
  "detail": "Failed to list services"
}

---

Integration with Client Apps

Mobile App Example (React Native)

// List services with projection
const response = await fetch('http://api.example.com/customer/services/list', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    category: 'Hair Services',
    status: 'active',
    limit: 20,
    offset: 0,
    projection_list: ['service_id', 'name', 'price', 'duration_mins']
  })
});

const services = await response.json();

Web App Example (JavaScript)

// Get service details
const response = await fetch(`http://api.example.com/customer/services/${serviceId}`);
const service = await response.json();

---

Performance Tips

1. Use Projection: Always use projection_list to request only needed fields
2. Pagination: Use appropriate limit values (20-50 recommended)
3. Caching: Cache service lists on client side with TTL
4. Filters: Apply filters server-side rather than client-side filtering

---

Data Flow

Client App
    ↓
SPA-MS (/customer/services/list)
    ↓
MongoDB (scm_service_catalogue collection)
    ↓
Transform to customer-safe format
    ↓
Apply projection (if requested)
    ↓
Return to client

---

Notes

• All services are read from scm_service_catalogue MongoDB collection
• No authentication required (configure as needed)
• Customer-safe data only (no internal audit fields exposed)
• Projection support for performance optimization
• Follows API List Endpoint Standard
• Compatible with mobile and web client apps