Autoparts-DB/docs/API.md

# API Reference - Nexus Autoparts

Documentación completa de la API REST del sistema Nexus Autoparts.

## Base URL

```
http://localhost:5000/api
```

## Endpoints

### GET /api/brands

Obtiene la lista de todas las marcas de vehículos disponibles.

**Request:**
```bash
curl http://localhost:5000/api/brands
```

**Response:**
```json
{
  "brands": [
    {
      "id": 1,
      "name": "Toyota",
      "country": "Japan",
      "founded_year": 1937
    },
    {
      "id": 2,
      "name": "Honda",
      "country": "Japan",
      "founded_year": 1948
    }
  ]
}
```

---

### GET /api/models

Obtiene modelos de vehículos, opcionalmente filtrados por marca.

**Parámetros:**
| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| brand | string | No | Nombre de la marca para filtrar |

**Request:**
```bash
# Todos los modelos
curl http://localhost:5000/api/models

# Modelos de Toyota
curl "http://localhost:5000/api/models?brand=Toyota"
```

**Response:**
```json
{
  "models": [
    {
      "id": 1,
      "name": "Camry",
      "brand": "Toyota",
      "body_type": "Sedan",
      "generation": "XV70",
      "production_start_year": 2017,
      "production_end_year": null
    }
  ]
}
```

---

### GET /api/years

Obtiene todos los años disponibles en la base de datos.

**Request:**
```bash
curl http://localhost:5000/api/years
```

**Response:**
```json
{
  "years": [1990, 1991, 1992, ..., 2024, 2025]
}
```

---

### GET /api/engines

Obtiene todos los motores disponibles.

**Request:**
```bash
curl http://localhost:5000/api/engines
```

**Response:**
```json
{
  "engines": [
    {
      "id": 1,
      "name": "2.5L 4-Cylinder",
      "displacement_cc": 2500,
      "cylinders": 4,
      "fuel_type": "Gasoline",
      "power_hp": 203,
      "torque_nm": 250,
      "engine_code": "A25A-FKS"
    }
  ]
}
```

---

### GET /api/vehicles

Búsqueda de vehículos con múltiples filtros.

**Parámetros:**
| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| brand | string | No | Marca del vehículo |
| model | string | No | Modelo del vehículo |
| year | integer | No | Año del vehículo |
| engine | string | No | Nombre/código del motor |
| limit | integer | No | Límite de resultados (default: 100) |

**Request:**
```bash
# Búsqueda completa
curl "http://localhost:5000/api/vehicles?brand=Toyota&model=Camry&year=2020"

# Solo por marca
curl "http://localhost:5000/api/vehicles?brand=Honda"

# Con límite
curl "http://localhost:5000/api/vehicles?brand=Ford&limit=50"
```

**Response:**
```json
{
  "vehicles": [
    {
      "brand": "Toyota",
      "model": "Camry",
      "year": 2020,
      "body_type": "Sedan",
      "generation": "XV70",
      "engine_name": "2.5L 4-Cylinder",
      "displacement_cc": 2500,
      "cylinders": 4,
      "fuel_type": "Gasoline",
      "power_hp": 203,
      "torque_nm": 250,
      "engine_code": "A25A-FKS",
      "trim_level": "LE",
      "drivetrain": "FWD",
      "transmission": "8-Speed Automatic"
    }
  ],
  "total": 1
}
```

---

## Códigos de Respuesta

| Código | Descripción |
|--------|-------------|
| 200 | OK - Solicitud exitosa |
| 400 | Bad Request - Parámetros inválidos |
| 404 | Not Found - Recurso no encontrado |
| 500 | Internal Server Error - Error del servidor |

## Manejo de Errores

Todas las respuestas de error siguen el formato:

```json
{
  "error": "Descripción del error",
  "code": 400
}
```

## Ejemplos de Uso

### Python

```python
import requests

BASE_URL = "http://localhost:5000/api"

# Obtener marcas
response = requests.get(f"{BASE_URL}/brands")
brands = response.json()["brands"]

# Buscar vehículos
params = {
    "brand": "Toyota",
    "year": 2020,
    "limit": 50
}
response = requests.get(f"{BASE_URL}/vehicles", params=params)
vehicles = response.json()["vehicles"]
```

### JavaScript

```javascript
const BASE_URL = 'http://localhost:5000/api';

// Obtener marcas
async function getBrands() {
    const response = await fetch(`${BASE_URL}/brands`);
    const data = await response.json();
    return data.brands;
}

// Buscar vehículos
async function searchVehicles(filters) {
    const params = new URLSearchParams(filters);
    const response = await fetch(`${BASE_URL}/vehicles?${params}`);
    const data = await response.json();
    return data.vehicles;
}

// Uso
const vehicles = await searchVehicles({
    brand: 'Toyota',
    year: 2020
});
```

### cURL

```bash
# Obtener todas las marcas
curl -X GET http://localhost:5000/api/brands

# Buscar vehículos Toyota del 2020
curl -X GET "http://localhost:5000/api/vehicles?brand=Toyota&year=2020"

# Obtener modelos de Honda
curl -X GET "http://localhost:5000/api/models?brand=Honda"
```

## Rate Limiting

Actualmente no hay límites de tasa implementados. Para uso en producción, se recomienda implementar rate limiting.

## CORS

El servidor está configurado para aceptar solicitudes desde cualquier origen (CORS habilitado). Para producción, configure los orígenes permitidos apropiadamente.