# REST API Endpoints Documentation

## Base URL
```
/wp-json/multilingual-press-zone/v1
```

## Authentication
- Read endpoints: Public access
- Write endpoints: Requires WordPress authentication (manage_options capability)

---

## Languages API

### 1. Get All Languages
**GET** `/languages`

Query Parameters:
- `active_only` (boolean, optional) - Return only active languages

Example:
```bash
curl -X GET "https://yoursite.com/wp-json/multilingual-press-zone/v1/languages?active_only=true"
```

Response:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "en",
      "locale": "en_US",
      "name": "English",
      "native_name": "English",
      "flag_code": "US",
      "is_default": true,
      "is_active": true,
      "sort_order": 0,
      "url_structure": "subdirectory",
      "text_direction": "ltr"
    }
  ],
  "message": "Languages retrieved successfully"
}
```

### 2. Get Single Language
**GET** `/languages/{id}`

Example:
```bash
curl -X GET "https://yoursite.com/wp-json/multilingual-press-zone/v1/languages/1"
```

### 3. Create Language
**POST** `/languages`

Required Headers:
- `X-WP-Nonce: {nonce}` (Get from wp.rest.nonce in WordPress admin)

Body:
```json
{
  "code": "es",
  "locale": "es_ES",
  "name": "Spanish",
  "native_name": "Español",
  "flag_code": "ES",
  "text_direction": "ltr",
  "is_active": true,
  "sort_order": 1,
  "url_structure": "subdirectory"
}
```

Example:
```bash
curl -X POST "https://yoursite.com/wp-json/multilingual-press-zone/v1/languages" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

### 4. Update Language
**PUT** `/languages/{id}`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body (partial update allowed):
```json
{
  "name": "Spanish (Spain)",
  "is_active": true
}
```

### 5. Delete Language
**DELETE** `/languages/{id}`

Required Headers:
- `X-WP-Nonce: {nonce}`

Example:
```bash
curl -X DELETE "https://yoursite.com/wp-json/multilingual-press-zone/v1/languages/2" \
  -H "X-WP-Nonce: YOUR_NONCE"
```

### 6. Reorder Languages
**POST** `/languages/reorder`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body:
```json
{
  "order": [1, 3, 2, 4]
}
```

### 7. Set Default Language
**POST** `/languages/{id}/set-default`

Required Headers:
- `X-WP-Nonce: {nonce}`

---

## Translations API

### 1. Get Translations (with filters)
**GET** `/translations`

Query Parameters:
- `language_code` (string, optional) - Filter by language
- `status` (string, optional) - Filter by status (original, translated, needs_update, draft)
- `post_type` (string, optional) - Filter by post type
- `search` (string, optional) - Search in post titles
- `per_page` (integer, default: 20) - Results per page
- `page` (integer, default: 1) - Page number

Example:
```bash
curl -X GET "https://yoursite.com/wp-json/multilingual-press-zone/v1/translations?language_code=es&status=translated&per_page=10&page=1"
```

Response:
```json
{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 50,
    "page": 1,
    "per_page": 10,
    "pages": 5
  },
  "message": "Translations retrieved successfully"
}
```

### 2. Get Single Translation
**GET** `/translations/{id}`

Returns all translations for a post.

### 3. Create Translation Record
**POST** `/translations`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body:
```json
{
  "post_id": 123,
  "language_id": 2
}
```

### 4. Link Translations
**POST** `/translations/link`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body:
```json
{
  "source_post_id": 123,
  "target_post_id": 456,
  "target_language_id": 2
}
```

### 5. Queue Translation Job
**POST** `/translations/translate`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body:
```json
{
  "post_id": 123,
  "target_language_ids": [2, 3, 4]
}
```

### 6. Get Translation Group
**GET** `/translations/groups/{groupId}`

Returns all posts in a translation group.

### 7. Unlink Translation
**DELETE** `/translations/{id}`

Required Headers:
- `X-WP-Nonce: {nonce}`

---

## Settings API

### 1. Get All Settings
**GET** `/settings`

Required Headers:
- `X-WP-Nonce: {nonce}`

Response:
```json
{
  "success": true,
  "data": {
    "general": {
      "default_language": "en",
      "auto_translate_on_publish": false,
      "show_language_switcher": true,
      "url_structure": "subdirectory"
    },
    "api": {
      "api_url": "https://api.press.zone",
      "api_key_set": true,
      "timeout": 30
    },
    "cache": {
      "enabled": true,
      "ttl": 3600,
      "use_object_cache": false
    },
    "performance": {
      "query_optimization": true,
      "prefetch_translations": true,
      "batch_size": 50,
      "warm_cache_on_activation": true
    },
    "advanced": {
      "debug_mode": false,
      "log_queries": false,
      "enable_rest_api": true
    }
  }
}
```

### 2. Update Settings
**PUT** `/settings`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body (partial update allowed):
```json
{
  "auto_translate_on_publish": true,
  "cache_ttl": 7200,
  "batch_size": 75
}
```

### 3. Test API Connection
**POST** `/settings/test-connection`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body (optional - uses saved settings if not provided):
```json
{
  "api_url": "https://api.press.zone",
  "api_key": "your-api-key"
}
```

### 4. Clear Cache
**POST** `/settings/clear-cache`

Required Headers:
- `X-WP-Nonce: {nonce}`

### 5. Reset Settings
**POST** `/settings/reset`

Required Headers:
- `X-WP-Nonce: {nonce}`

Body:
```json
{
  "confirm": true
}
```

### 6. Get Cache Statistics
**GET** `/settings/cache-stats`

Required Headers:
- `X-WP-Nonce: {nonce}`

Response:
```json
{
  "success": true,
  "data": {
    "statistics": {
      "memory_cache": {
        "hits": 150,
        "misses": 20,
        "size": 45,
        "max_size": 1000
      },
      "object_cache": {
        "hits": 80,
        "misses": 10,
        "available": false
      },
      "transient_cache": {
        "hits": 30,
        "misses": 5,
        "available": true
      },
      "totals": {
        "hits": 260,
        "misses": 35,
        "requests": 295,
        "hit_ratio": 88.14
      }
    }
  }
}
```

---

## Error Responses

All endpoints return errors in this format:

```json
{
  "code": "error_code",
  "message": "Error description",
  "data": {
    "status": 400
  }
}
```

Common HTTP Status Codes:
- `200` - Success
- `201` - Created
- `400` - Bad Request (validation error)
- `403` - Forbidden (permission denied)
- `404` - Not Found
- `500` - Internal Server Error

---

## Testing with WordPress Admin

Get the nonce value from browser console:
```javascript
console.log(wpApiSettings.nonce);
// or
console.log(wp.rest.nonce);
```

Then use it in your API requests:
```javascript
fetch('/wp-json/multilingual-press-zone/v1/languages', {
  method: 'GET',
  headers: {
    'X-WP-Nonce': wp.rest.nonce
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

---

## Rate Limiting

Currently no rate limiting is implemented. This may be added in future versions.

---

## Changelog

### Version 1.0.0
- Initial REST API implementation
- Languages CRUD endpoints
- Translations management endpoints
- Settings management endpoints
- Cache statistics endpoint