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)
```http
POST /customer/services/list
```

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

**Response (with projection)**:
```json
[
  {
    "service_id": "uuid",
    "name": "Hair Cut",
    "price": 500.00,
    "duration_mins": 30
  }
]
```

**Response (without projection)**:
```json
{
  "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
```http
GET /customer/services/{service_id}
```

**Response**: `CustomerServiceResponse`

---

### 3. Legacy GET List (Deprecated)
```http
GET /customer/services?category=Hair%20Services&status=active&limit=20&offset=0
```

**Note**: Use POST /list instead for projection support.

---

## Request Schema

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

---

## Response Schema

### CustomerServiceResponse
```json
{
  "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
```bash
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
```bash
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)
```bash
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
```bash
curl -X GET "http://localhost:8000/customer/services/{service_id}"
```

---

## Filters

### category
Filter services by category name (case-insensitive).

**Example**:
```json
{
  "category": "Hair Services"
}
```

### status
Filter services by status.

**Valid Values**: `active`, `inactive`, `archived`

**Example**:
```json
{
  "status": "active"
}
```

---

## Pagination

Use `limit` and `offset` for pagination:

```json
{
  "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):
```json
{
  "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):
```json
{
  "service_id": "uuid",
  "name": "Hair Cut",
  "price": 500.00,
  "duration_mins": 30
}
```

**Payload Reduction**: ~70% smaller

---

## Error Responses

### 404 Not Found
```json
{
  "detail": "Service with ID 'xyz' not found"
}
```

### 422 Validation Error
```json
{
  "detail": [
    {
      "loc": ["body", "status"],
      "msg": "Status must be one of: active, inactive, archived",
      "type": "value_error"
    }
  ]
}
```

### 500 Internal Server Error
```json
{
  "detail": "Failed to list services"
}
```

---

## Integration with Client Apps

### Mobile App Example (React Native)
```javascript
// 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)
```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