michaelschiemer/docs/search-api-examples.md

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:

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:

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

Advanced Search with Filters:

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:

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:

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

Field Boosting:

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

{
  "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.

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

{
  "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.

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

{
  "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.

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.

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.

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

Response

{
  "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.

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

Response

{
  "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.

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.

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

{
  "category": {
    "type": "equals",
    "value": "smartphones"
  }
}

In (Array)

{
  "category": {
    "type": "in", 
    "value": ["smartphones", "tablets", "laptops"]
  }
}

Range

{
  "price": {
    "type": "range",
    "value": {
      "min": 500,
      "max": 1500
    }
  }
}

Greater/Less Than

{
  "price": {
    "type": "greater_than",
    "value": 1000
  },
  "stock": {
    "type": "less_than", 
    "value": 10
  }
}

Contains (Text Search)

{
  "description": {
    "type": "contains",
    "value": "wireless"
  }
}

Exists/Not Exists

{
  "discount": {
    "type": "exists"
  },
  "legacy_field": {
    "type": "not_exists"
  }
}

Error Handling

All endpoints return consistent error responses:

{
  "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