image-apiv3/API_README.md

# Image API - Resim Manipülasyon API Dokümantasyonu

Bu API, dış uygulamaların resim yükleme, manipülasyon ve yönetim işlemlerini yapmasına olanak tanır.

## Base URL
```
https://image.beyhano.com.tr
# veya development için
http://localhost:3000
```

## Authentication

API, JWT token tabanlı kimlik doğrulama kullanır. Her istekte `Authorization` header'ında Bearer token gönderilmelidir.

```
Authorization: Bearer <your_jwt_token>
```

## Endpoints

### 1. Kayıt Ol (Register)

Yeni kullanıcı kaydı oluşturur ve JWT token döner.

**Endpoint:** `POST /api/v1/auth/register`

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "minimum8karakter",
  "name": "Kullanıcı Adı"
}
```

**Response (200):**
```json
{
  "success": true,
  "message": "Kayıt başarılı",
  "data": {
    "user": {
      "id": "user_123abc",
      "email": "user@example.com",
      "name": "Kullanıcı Adı"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**Hata Kodları:**
- `400` - Gerekli alanlar eksik veya geçersiz
- `409` - Email adresi zaten kullanımda
- `500` - Sunucu hatası

---

### 2. Giriş Yap (Login)

Mevcut kullanıcı ile giriş yapar ve JWT token döner.

**Endpoint:** `POST /api/v1/auth/login`

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "minimum8karakter"
}
```

**Response (200):**
```json
{
  "success": true,
  "message": "Giriş başarılı",
  "data": {
    "user": {
      "id": "user_123abc",
      "email": "user@example.com",
      "name": "Kullanıcı Adı"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**Hata Kodları:**
- `400` - Email veya şifre eksik
- `401` - Geçersiz email veya şifre
- `500` - Sunucu hatası

---

### 3. Resim Yükle ve Manipüle Et

Resim yükler, belirtilen boyut/kalite/formatta işler ve kaydeder.

**Endpoint:** `POST /api/v1/images/upload`

**Headers:**
```
Authorization: Bearer <your_jwt_token>
Content-Type: multipart/form-data
```

**Request Body (FormData):**
- `file` (required): Resim dosyası (max 10MB)
- `width` (optional): Genişlik (px), default: 800, max: 10000
- `height` (optional): Yükseklik (px), default: 600, max: 10000
- `quality` (optional): Kalite (1-100), default: 90
- `format` (optional): Format (jpeg, png, webp, avif), default: jpeg

**cURL Örneği:**
```bash
curl -X POST https://image.beyhano.com.tr/api/v1/images/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "width=1920" \
  -F "height=1080" \
  -F "quality=85" \
  -F "format=webp"
```

**Response (200):**
```json
{
  "success": true,
  "message": "Resim başarıyla yüklendi",
  "data": {
    "image": {
      "id": "img_xyz789",
      "url": "https://image.beyhano.com.tr/uploads/xyz789.webp",
      "width": 1920,
      "height": 1080,
      "format": "webp",
      "fileSize": 245678
    }
  }
}
```

**Hata Kodları:**
- `400` - Dosya eksik, boyut çok büyük veya geçersiz tip
- `401` - Geçersiz veya eksik token
- `500` - Sunucu hatası

---

### 4. Resimleri Listele

Kullanıcının tüm resimlerini listeler.

**Endpoint:** `GET /api/v1/images`

**Headers:**
```
Authorization: Bearer <your_jwt_token>
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "images": [
      {
        "id": "img_xyz789",
        "originalName": "photo.jpg",
        "url": "https://image.beyhano.com.tr/uploads/xyz789.webp",
        "width": 1920,
        "height": 1080,
        "quality": 85,
        "format": "webp",
        "fileSize": 245678,
        "createdAt": "2026-01-06T02:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

**Hata Kodları:**
- `401` - Geçersiz veya eksik token
- `500` - Sunucu hatası

---

### 5. Resim Sil

Belirtilen ID'ye sahip resmi siler.

**Endpoint:** `DELETE /api/v1/images/{id}`

**Headers:**
```
Authorization: Bearer <your_jwt_token>
```

**cURL Örneği:**
```bash
curl -X DELETE https://image.beyhano.com.tr/api/v1/images/img_xyz789 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response (200):**
```json
{
  "success": true,
  "message": "Resim başarıyla silindi"
}
```

**Hata Kodları:**
- `401` - Geçersiz veya eksik token
- `404` - Resim bulunamadı veya size ait değil
- `500` - Sunucu hatası

---

## Örnek Kullanım (JavaScript/Node.js)

```javascript
// 1. Kayıt ol
const registerResponse = await fetch('https://image.beyhano.com.tr/api/v1/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securepassword123',
    name: 'Kullanıcı'
  })
});
const { data } = await registerResponse.json();
const token = data.accessToken;

// 2. Resim yükle
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('width', '1920');
formData.append('height', '1080');
formData.append('quality', '85');
formData.append('format', 'webp');

const uploadResponse = await fetch('https://image.beyhano.com.tr/api/v1/images/upload', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: formData
});
const uploadData = await uploadResponse.json();
console.log('Yüklenen resim:', uploadData.data.image.url);

// 3. Resimleri listele
const imagesResponse = await fetch('https://image.beyhano.com.tr/api/v1/images', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const imagesData = await imagesResponse.json();
console.log('Toplam resim:', imagesData.data.total);

// 4. Resim sil
const deleteResponse = await fetch(`https://image.beyhano.com.tr/api/v1/images/${imageId}`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${token}` }
});
const deleteData = await deleteResponse.json();
console.log(deleteData.message);
```

## Örnek Kullanım (Python)

```python
import requests

# 1. Kayıt ol
register_response = requests.post(
    'https://image.beyhano.com.tr/api/v1/auth/register',
    json={
        'email': 'user@example.com',
        'password': 'securepassword123',
        'name': 'Kullanıcı'
    }
)
token = register_response.json()['data']['accessToken']

# 2. Resim yükle
with open('image.jpg', 'rb') as f:
    upload_response = requests.post(
        'https://image.beyhano.com.tr/api/v1/images/upload',
        headers={'Authorization': f'Bearer {token}'},
        files={'file': f},
        data={
            'width': '1920',
            'height': '1080',
            'quality': '85',
            'format': 'webp'
        }
    )
image_url = upload_response.json()['data']['image']['url']
print(f'Yüklenen resim: {image_url}')

# 3. Resimleri listele
images_response = requests.get(
    'https://image.beyhano.com.tr/api/v1/images',
    headers={'Authorization': f'Bearer {token}'}
)
images = images_response.json()['data']['images']
print(f'Toplam resim: {len(images)}')

# 4. Resim sil
delete_response = requests.delete(
    f'https://image.beyhano.com.tr/api/v1/images/{image_id}',
    headers={'Authorization': f'Bearer {token}'}
)
print(delete_response.json()['message'])
```

## Güvenlik

- JWT token'lar 7 gün geçerlidir
- Şifreler bcrypt ile hashlenmiş olarak saklanır
- Token'ları güvenli bir şekilde saklayın
- HTTPS kullanın (production'da)
- Rate limiting uygulanabilir

## Limitler

- Maximum dosya boyutu: 10MB
- Maximum resim boyutu: 10000x10000 px
- Desteklenen formatlar: JPEG, PNG, WebP, AVIF, GIF
- JWT token geçerlilik süresi: 7 gün

## Hata Yönetimi

Tüm hata yanıtları şu formatta döner:

```json
{
  "error": "Hata mesajı burada"
}
```

HTTP status kodları:
- `200` - Başarılı
- `400` - Kötü istek (geçersiz parametreler)
- `401` - Kimlik doğrulama hatası
- `404` - Bulunamadı
- `409` - Çakışma (örn: email zaten kullanımda)
- `500` - Sunucu hatası