# Goondex API Quick Reference

**Quick lookup for all API endpoints**

## Base URL
```
http://localhost:8080
```

---

## Search & Import APIs

| Method | Endpoint | Description | Request Body |
|--------|----------|-------------|--------------|
| `POST` | `/api/import/performer` | Import performer by name search | `{"query": "name"}` |
| `POST` | `/api/import/studio` | Import studio by name search | `{"query": "name"}` |
| `POST` | `/api/import/scene` | Import scene by title search | `{"query": "title"}` |

---

## Bulk Import APIs

| Method | Endpoint | Description | Request Body |
|--------|----------|-------------|--------------|
| `POST` | `/api/import/all` | Import all data (performers, studios, scenes) | None |
| `POST` | `/api/import/all-performers` | Import all performers from database | None |
| `POST` | `/api/import/all-studios` | Import all studios from database | None |
| `POST` | `/api/import/all-scenes` | Import all scenes from database | None |

---

## Bulk Import with Real-time Progress (SSE)

| Method | Endpoint | Description | Returns |
|--------|----------|-------------|---------|
| `GET` | `/api/import/all-performers/progress` | Import performers with SSE updates | Event stream |
| `GET` | `/api/import/all-studios/progress` | Import studios with SSE updates | Event stream |
| `GET` | `/api/import/all-scenes/progress` | Import scenes with SSE updates | Event stream |

---

## Sync APIs

| Method | Endpoint | Description | Request Body |
|--------|----------|-------------|--------------|
| `POST` | `/api/sync` | Sync all data with TPDB | `{"force": true/false}` (optional) |
| `GET` | `/api/sync/status` | Get last sync timestamp for all entities | None |

---

## Search API

| Method | Endpoint | Description | Query Params |
|--------|----------|-------------|--------------|
| `GET` | `/api/search` | Global search across all entities | `?q=search_term` |

**Response:**
```javascript
{
  "success": true,
  "message": "Found 25 results",
  "data": {
    "performers": [...],
    "studios": [...],
    "scenes": [...],
    "tags": [...],
    "total": 25
  }
}
```

---

## Quick Examples

### Import a Performer
```javascript
fetch('http://localhost:8080/api/import/performer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'Jane Doe' })
})
.then(res => res.json())
.then(data => console.log(data));
```

### Global Search
```javascript
fetch('http://localhost:8080/api/search?q=search_term')
  .then(res => res.json())
  .then(data => console.log(data.data));
```

### Bulk Import with Progress
```javascript
const eventSource = new EventSource(
  'http://localhost:8080/api/import/all-performers/progress'
);

eventSource.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log(update);

  if (update.complete) {
    eventSource.close();
  }
};
```

### Sync Data
```javascript
fetch('http://localhost:8080/api/sync', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ force: false })
})
.then(res => res.json())
.then(data => console.log(data));
```

---

## Standard Response Format

All endpoints return JSON in this format:

```javascript
{
  "success": true,      // boolean
  "message": "...",     // string
  "data": { ... }       // object (optional)
}
```

**Success Response:**
```javascript
{
  "success": true,
  "message": "Imported 5 performer(s)",
  "data": { "imported": 5, "found": 5 }
}
```

**Error Response:**
```javascript
{
  "success": false,
  "message": "TPDB_API_KEY not configured"
}
```

---

## Common HTTP Status Codes

| Code | Meaning |
|------|---------|
| `200` | Success |
| `400` | Bad Request (invalid data) |
| `404` | Not Found |
| `405` | Method Not Allowed (e.g., GET instead of POST) |
| `500` | Internal Server Error |

---

## HTML/Page Routes (for reference)

These serve HTML pages, not JSON:

| Route | Description |
|-------|-------------|
| `/` | Dashboard |
| `/performers` | Performer list |
| `/performers/{id}` | Performer detail |
| `/studios` | Studio list |
| `/studios/{id}` | Studio detail |
| `/scenes` | Scene list |
| `/scenes/{id}` | Scene detail |
| `/movies` | Movie list |
| `/movies/{id}` | Movie detail |

Query parameters for lists:
- `?q=search_term` - Search filter
- `?nationality=US` - Filter performers by nationality
- `?gender=female` - Filter performers by gender

---

## Environment Setup

Make sure the backend is configured with:

```bash
export TPDB_API_KEY="your-api-key-here"
```

Without this, import and sync endpoints will fail with:
```javascript
{
  "success": false,
  "message": "TPDB_API_KEY not configured"
}
```