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:

{
  "email": "user@example.com",
  "password": "minimum8karakter",
  "name": "Kullanıcı Adı"
}

Response (200):

{
  "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:

{
  "email": "user@example.com",
  "password": "minimum8karakter"
}

Response (200):

{
  "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:

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):

{
  "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):

{
  "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:

curl -X DELETE https://image.beyhano.com.tr/api/v1/images/img_xyz789 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response (200):

{
  "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)

// 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)

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:

{
  "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ı