opensearch-api 0.1.0

# OpenSearch API - Documentação Completa

## 📚 Índice
- [Visão Geral](#visão-geral)
- [Instalação](#instalação)
- [Configuração](#configuração)
- [Autenticação](#autenticação)
- [Endpoints da API](#endpoints-da-api)
- [Exemplos de Uso](#exemplos-de-uso)
- [Monitoramento](#monitoramento)
- [Troubleshooting](#troubleshooting)

## Visão Geral

OpenSearch API é uma interface REST de alta performance desenvolvida em Rust para interagir com clusters OpenSearch/Elasticsearch. Fornece uma camada de abstração simplificada com autenticação, rate limiting e monitoramento integrados.

### Características Principais
- 🚀 Alta performance com Rust/Axum
- 🔐 Autenticação via JWT e API Keys
- 📊 Métricas Prometheus integradas
- 🔄 Migração automática ES → OpenSearch
- 🛡️ CORS e compressão GZIP
- 📝 Logging estruturado

## Instalação

### Requisitos
- Linux (Ubuntu 20.04+ / CentOS 8+ / Debian 11+)
- 2GB RAM mínimo
- 10GB espaço em disco
- OpenSearch 2.x ou Elasticsearch 7.x

### Instalação Rápida
```bash
curl -L https://aerun.com.br/products/opensearch-api/install.sh | sudo bash
```

### Instalação Manual
```bash
# Clone o repositório
git clone https://github.com/aerun/opensearch-api.git
cd opensearch-api

# Compile em modo release
cargo build --release

# Copie o binário
sudo cp target/release/opensearch-api /usr/local/bin/

# Configure o serviço
sudo cp opensearch-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable opensearch-api
```

## Configuração

### Arquivo .env
```env
# Endereço de bind da API
ADDR=0.0.0.0:3000

# URL do OpenSearch/Elasticsearch
OPENSEARCH_URL=http://localhost:9200

# Nível de log (trace, debug, info, warn, error)
LOG_LEVEL=info

# Autenticação
JWT_SECRET=your-secret-key-change-in-production
API_KEY_SALT=random-salt-for-api-keys

# Rate Limiting (requisições por minuto)
RATE_LIMIT=1000

# Métricas Prometheus
METRICS_ENABLED=true
METRICS_PORT=9090
```

### Configuração do Systemd
```ini
[Unit]
Description=OpenSearch API Service
After=network.target opensearch.service

[Service]
Type=simple
User=opensearch-api
EnvironmentFile=/etc/opensearch-api/.env
ExecStart=/usr/local/bin/opensearch-api
Restart=always

[Install]
WantedBy=multi-user.target
```

## Autenticação

### 1. JWT (JSON Web Tokens)

#### Login
```bash
POST /auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "senha123"
}

# Resposta
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user_id": "admin_001",
  "role": "admin"
}
```

#### Usando o Token
```bash
GET /indices
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### 2. API Keys

#### Gerar API Key (requer role admin)
```bash
POST /auth/api-key
Authorization: Bearer <admin-jwt-token>

# Resposta
{
  "key": "sk_live_a1b2c3d4e5f6...",
  "name": "Production Key",
  "role": "api_user",
  "created_at": 1704067200
}
```

#### Usando API Key
```bash
GET /indices
X-API-Key: sk_live_a1b2c3d4e5f6...
```

## Endpoints da API

### Health Check

#### GET /
Retorna versão da API
```bash
curl http://localhost:3000/

# Resposta
"OpenSearch API v0.1.0"
```

#### GET /health
Status detalhado do serviço
```bash
curl http://localhost:3000/health

# Resposta
{
  "status": "healthy",
  "opensearch_url": "http://localhost:9200",
  "version": "0.1.0"
}
```

### Gerenciamento de Índices

#### GET /indices
Lista todos os índices
```bash
curl -H "X-API-Key: sk_live_..." http://localhost:3000/indices

# Resposta
[
  {
    "index": "products",
    "health": "green",
    "docs.count": "1234",
    "store.size": "5.2mb"
  }
]
```

#### GET /indices/{index_name}
Informações detalhadas de um índice
```bash
curl -H "X-API-Key: sk_live_..." http://localhost:3000/indices/products

# Resposta
{
  "products": {
    "mappings": {...},
    "settings": {...}
  }
}
```

### Indexação de Documentos

#### POST /index/{index_name}
Adiciona documento ao índice
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{
    "title": "Produto Exemplo",
    "price": 99.90,
    "category": "electronics"
  }' \
  http://localhost:3000/index/products

# Resposta
{
  "id": "AbC123XyZ",
  "index": "products",
  "result": "created"
}
```

### Busca

#### GET /search/{index_name}
Busca documentos em um índice
```bash
curl -H "X-API-Key: sk_live_..." \
  "http://localhost:3000/search/products?q=laptop&size=10&from=0"

# Resposta
{
  "hits": [
    {
      "title": "Laptop Dell XPS",
      "price": 1999.90,
      "category": "electronics"
    }
  ],
  "total": 42,
  "took": 15
}
```

Parâmetros de query:
- `q` (obrigatório): Termo de busca
- `size` (opcional, padrão: 10): Número de resultados
- `from` (opcional, padrão: 0): Offset para paginação

### Métricas

#### GET /metrics
Métricas no formato Prometheus
```bash
curl http://localhost:9090/metrics

# Resposta (formato Prometheus)
# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",endpoint="/search",status="200"} 1234
```

## Exemplos de Uso

### Python
```python
import requests
import json

class OpenSearchAPI:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.headers = {"X-API-Key": api_key}
    
    def index_document(self, index, document):
        response = requests.post(
            f"{self.base_url}/index/{index}",
            headers=self.headers,
            json=document
        )
        return response.json()
    
    def search(self, index, query, size=10):
        response = requests.get(
            f"{self.base_url}/search/{index}",
            headers=self.headers,
            params={"q": query, "size": size}
        )
        return response.json()

# Uso
api = OpenSearchAPI("http://localhost:3000", "sk_live_...")
api.index_document("products", {"name": "iPhone", "price": 999})
results = api.search("products", "phone")
```

### Node.js
```javascript
const axios = require('axios');

class OpenSearchAPI {
  constructor(baseUrl, apiKey) {
    this.client = axios.create({
      baseURL: baseUrl,
      headers: { 'X-API-Key': apiKey }
    });
  }

  async indexDocument(index, document) {
    const response = await this.client.post(`/index/${index}`, document);
    return response.data;
  }

  async search(index, query, size = 10) {
    const response = await this.client.get(`/search/${index}`, {
      params: { q: query, size }
    });
    return response.data;
  }
}

// Uso
const api = new OpenSearchAPI('http://localhost:3000', 'sk_live_...');
await api.indexDocument('products', { name: 'iPhone', price: 999 });
const results = await api.search('products', 'phone');
```

### cURL
```bash
# Indexar documento
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{"name":"iPhone","price":999}' \
  http://localhost:3000/index/products

# Buscar
curl -H "X-API-Key: sk_live_..." \
  "http://localhost:3000/search/products?q=phone"

# Listar índices
curl -H "X-API-Key: sk_live_..." \
  http://localhost:3000/indices
```

## Monitoramento

### Prometheus Configuration
```yaml
# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'opensearch-api'
    static_configs:
      - targets: ['localhost:9090']
```

### Grafana Dashboard
Importe o dashboard usando o ID: `opensearch-api-dashboard`

Métricas disponíveis:
- Request rate por endpoint
- Latência P50/P95/P99
- Taxa de erro
- Conexões ativas
- Uso de memória

## Troubleshooting

### Erro: Connection Refused
```bash
# Verificar se OpenSearch está rodando
curl http://localhost:9200

# Verificar logs da API
journalctl -u opensearch-api -f
```

### Erro: Authentication Failed
```bash
# Verificar validade do token JWT
# Tokens expiram em 24 horas

# Gerar novo token
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  http://localhost:3000/auth/login
```

### Performance Issues
```bash
# Verificar métricas
curl http://localhost:9090/metrics | grep http_request_duration

# Ajustar pool de conexões no .env
CONNECTION_POOL_SIZE=50
```

### Logs
```bash
# Ver logs em tempo real
journalctl -u opensearch-api -f

# Logs dos últimos 100 eventos
journalctl -u opensearch-api -n 100

# Logs com nível debug
LOG_LEVEL=debug systemctl restart opensearch-api
```

## Migração ES → OpenSearch

Use o script de migração incluído:
```bash
sudo python3 opensearch-manager.py

# Selecione a opção de migração
# O script irá:
# 1. Detectar instalação do Elasticsearch
# 2. Instalar OpenSearch em paralelo
# 3. Migrar dados via reindex ou snapshot
# 4. Validar migração
# 5. Substituir Elasticsearch por OpenSearch
```

## Suporte

- 📧 Email: support@aerun.com.br
- 📚 Docs: https://docs.aerun.com.br/opensearch-api
- 🐛 Issues: https://github.com/aerun/opensearch-api/issues

## Licença

Software proprietário - Aerun Solutions © 2025
Requer licença válida para uso em produção.