# Search API Examples

This framework provides a comprehensive RESTful API for full-text search functionality.

## Base URL

All search endpoints are available under `/api/search/`

## Authentication

Search endpoints require a valid User-Agent header to avoid triggering firewall rules:

```bash
curl -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
     https://localhost/api/search/...
```

## API Endpoints

### 1. Search Documents

**GET** `/api/search/{entityType}`

Search for documents of a specific entity type.

#### Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `q` | string | Search query | `*` |
| `limit` | integer | Results per page (1-100) | `20` |
| `offset` | integer | Results offset | `0` |
| `page` | integer | Page number (alternative to offset) | `1` |
| `per_page` | integer | Results per page when using page | `20` |
| `fields` | string/array | Comma-separated fields to return | all |
| `highlight` | string/array | Fields to highlight | `title,content,description` |
| `sort_by` | string | Field to sort by | - |
| `sort_direction` | string | `asc` or `desc` | `asc` |
| `sort_by_relevance` | boolean | Sort by relevance score | `true` |
| `enable_highlighting` | boolean | Enable result highlighting | `true` |
| `enable_fuzzy` | boolean | Enable fuzzy matching | `false` |
| `min_score` | float | Minimum relevance score | `0.0` |

#### Examples

**Basic Search:**
```bash
curl -H "User-Agent: Mozilla/5.0" \
     "https://localhost/api/search/products?q=iPhone"
```

**Advanced Search with Filters:**
```bash
curl -H "User-Agent: Mozilla/5.0" \
     "https://localhost/api/search/products?q=smartphone&filter[category][type]=equals&filter[category][value]=electronics&filter[price][type]=range&filter[price][value][min]=500&filter[price][value][max]=1500"
```

**Search with JSON Filters:**
```bash
curl -H "User-Agent: Mozilla/5.0" \
     -H "Content-Type: application/json" \
     "https://localhost/api/search/products?q=laptop&filters=%7B%22category%22%3A%7B%22type%22%3A%22equals%22%2C%22value%22%3A%22computers%22%7D%2C%22price%22%3A%7B%22type%22%3A%22range%22%2C%22value%22%3A%7B%22min%22%3A800%2C%22max%22%3A2000%7D%7D%7D"
```

**Pagination:**
```bash
curl -H "User-Agent: Mozilla/5.0" \
     "https://localhost/api/search/articles?q=technology&page=2&per_page=10"
```

**Field Boosting:**
```bash
curl -H "User-Agent: Mozilla/5.0" \
     "https://localhost/api/search/articles?q=artificial intelligence&boosts=%7B%22title%22%3A2.0%2C%22tags%22%3A1.5%7D"
```

#### Response Format

```json
{
  "success": true,
  "data": {
    "hits": [
      {
        "id": "1",
        "entity_type": "products", 
        "score": 1.2345,
        "source": {
          "title": "iPhone 15 Pro Max",
          "description": "Latest iPhone with advanced features",
          "category": "smartphones",
          "price": 1199
        },
        "highlight": {
          "title": ["<em>iPhone</em> 15 Pro Max"],
          "description": ["Latest <em>iPhone</em> with advanced features"]
        }
      }
    ],
    "total": 145,
    "max_score": 2.5432,
    "took": 23.45,
    "has_more": true,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  },
  "aggregations": {}
}
```

### 2. Index Document

**POST** `/api/search/{entityType}/{id}`

Index a single document for searching.

```bash
curl -X POST \
     -H "User-Agent: Mozilla/5.0" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "iPhone 15 Pro Max",
       "description": "Latest iPhone with advanced camera and A17 Pro chip",
       "category": "smartphones",
       "brand": "Apple",
       "price": 1199,
       "tags": ["phone", "apple", "premium"],
       "created_at": "2024-08-08T10:00:00Z"
     }' \
     https://localhost/api/search/products/iphone-15-pro-max
```

#### Response
```json
{
  "success": true,
  "data": {
    "entity_type": "products",
    "id": "iphone-15-pro-max", 
    "indexed": true,
    "message": "Document indexed successfully"
  }
}
```

### 3. Bulk Index Documents

**POST** `/api/search/{entityType}/bulk`

Index multiple documents at once.

```bash
curl -X POST \
     -H "User-Agent: Mozilla/5.0" \
     -H "Content-Type: application/json" \
     -d '{
       "documents": [
         {
           "id": "product-1",
           "data": {
             "title": "MacBook Pro 14",
             "description": "Professional laptop with M3 chip",
             "category": "laptops",
             "price": 1999
           }
         },
         {
           "id": "product-2", 
           "data": {
             "title": "iPad Air",
             "description": "Versatile tablet for work and play",
             "category": "tablets", 
             "price": 599
           },
           "metadata": {
             "priority": "high"
           }
         }
       ]
     }' \
     https://localhost/api/search/products/bulk
```

#### Response
```json
{
  "success": true,
  "data": {
    "entity_type": "products",
    "bulk_result": {
      "total": 2,
      "successful": 2,
      "failed": 0,
      "successful_ids": ["product-1", "product-2"],
      "failed_ids": [],
      "errors": {},
      "started_at": "2024-08-08T10:00:00Z",
      "finished_at": "2024-08-08T10:00:01Z",
      "duration_ms": 1234.56,
      "success_rate": 100
    }
  }
}
```

### 4. Update Document

**PUT** `/api/search/{entityType}/{id}`

Update an existing document in the search index.

```bash
curl -X PUT \
     -H "User-Agent: Mozilla/5.0" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "iPhone 15 Pro Max - Updated",
       "description": "Latest iPhone with enhanced features and longer battery life",
       "price": 1099
     }' \
     https://localhost/api/search/products/iphone-15-pro-max
```

### 5. Delete Document

**DELETE** `/api/search/{entityType}/{id}`

Remove a document from the search index.

```bash
curl -X DELETE \
     -H "User-Agent: Mozilla/5.0" \
     https://localhost/api/search/products/iphone-15-pro-max
```

## Index Management

### 6. Get Engine Statistics

**GET** `/api/search/_stats`

Get overall search engine statistics.

```bash
curl -H "User-Agent: Mozilla/5.0" \
     https://localhost/api/search/_stats
```

#### Response
```json
{
  "success": true,
  "data": {
    "engine_stats": {
      "engine_name": "Database",
      "version": "8.0.33",
      "is_healthy": true,
      "total_documents": 1250,
      "index_counts": {
        "products": 450,
        "articles": 800
      },
      "disk_usage_mb": 128.5,
      "memory_usage_mb": 45.2,
      "last_updated": "2024-08-08T10:00:00Z"
    },
    "available": true
  }
}
```

### 7. Get Index Statistics

**GET** `/api/search/{entityType}/_stats`

Get statistics for a specific index.

```bash
curl -H "User-Agent: Mozilla/5.0" \
     https://localhost/api/search/products/_stats
```

#### Response
```json
{
  "success": true,
  "data": {
    "index_stats": {
      "entity_type": "products",
      "document_count": 450,
      "index_size_mb": 67.3,
      "query_count": 0,
      "average_query_time_ms": 0.0,
      "last_indexed": "2024-08-08T09:30:00Z",
      "created_at": "2024-08-01T12:00:00Z"
    },
    "entity_type": "products"
  }
}
```

### 8. Create Index

**PUT** `/api/search/{entityType}/_index`

Create or update a search index with specific field configurations.

```bash
curl -X PUT \
     -H "User-Agent: Mozilla/5.0" \
     -H "Content-Type: application/json" \
     -d '{
       "fields": {
         "title": {
           "type": "text",
           "searchable": true,
           "highlightable": true,
           "boost": 2.0
         },
         "description": {
           "type": "text",
           "searchable": true,
           "highlightable": true,
           "boost": 1.0
         },
         "category": {
           "type": "keyword",
           "searchable": false,
           "filterable": true,
           "sortable": true
         },
         "price": {
           "type": "float",
           "searchable": false,
           "filterable": true,
           "sortable": true
         },
         "created_at": {
           "type": "datetime",
           "searchable": false,
           "filterable": true,
           "sortable": true
         }
       },
       "settings": {
         "min_score_threshold": 0.1
       }
     }' \
     https://localhost/api/search/products/_index
```

### 9. Delete Index

**DELETE** `/api/search/{entityType}/_index`

Delete a search index and all its documents.

```bash
curl -X DELETE \
     -H "User-Agent: Mozilla/5.0" \
     https://localhost/api/search/products/_index
```

## Filter Types

The search API supports various filter types:

### Equals
```json
{
  "category": {
    "type": "equals",
    "value": "smartphones"
  }
}
```

### In (Array)
```json
{
  "category": {
    "type": "in", 
    "value": ["smartphones", "tablets", "laptops"]
  }
}
```

### Range
```json
{
  "price": {
    "type": "range",
    "value": {
      "min": 500,
      "max": 1500
    }
  }
}
```

### Greater/Less Than
```json
{
  "price": {
    "type": "greater_than",
    "value": 1000
  },
  "stock": {
    "type": "less_than", 
    "value": 10
  }
}
```

### Contains (Text Search)
```json
{
  "description": {
    "type": "contains",
    "value": "wireless"
  }
}
```

### Exists/Not Exists
```json
{
  "discount": {
    "type": "exists"
  },
  "legacy_field": {
    "type": "not_exists"
  }
}
```

## Error Handling

All endpoints return consistent error responses:

```json
{
  "success": false,
  "error": {
    "message": "Search query cannot be empty",
    "code": "VAL_BUSINESS_RULE_VIOLATION",
    "details": {
      "field": "query",
      "provided_value": ""
    }
  }
}
```

## Common HTTP Status Codes

- `200 OK` - Successful search/get operation
- `201 Created` - Document indexed successfully
- `202 Accepted` - Bulk operation partially successful
- `400 Bad Request` - Invalid request parameters
- `404 Not Found` - Index or document not found
- `500 Internal Server Error` - Server error

## Performance Tips

1. **Use Field Restrictions**: Only request fields you need with the `fields` parameter
2. **Limit Results**: Use reasonable `limit` values (20-50 for UI, 100 max)
3. **Filter Before Search**: Use filters to narrow down results before full-text search
4. **Boost Important Fields**: Use field boosting for better relevance
5. **Batch Operations**: Use bulk indexing for multiple documents
6. **Index Only Searchable Data**: Don't index fields you'll never search