dj52/IMAGE_API_DOCS.md

Resim API Endpoint'leri ve Dosya Yönetimi Dokümantasyonu

Bu belge, Django projenize eklenen yeni resim API endpoint'lerini ve ilgili dosya yönetimi özelliklerini açıklamaktadır.

---

1. Resim Yükleme ve Optimizasyon API Endpoint'i

Bu endpoint, resimleri yüklemenizi, boyutlandırmanızı, formatlarını değiştirmenizi ve kalitelerini ayarlamanızı sağlar. Yüklenen resimler en-boy oranı korunarak hedef boyutlara sığdırılır ve boş kalan alanlar doldurulur.

• Endpoint: POST /api/v1/images/upload/
• İşlevsellik:
  • Kullanıcı tarafından gönderilen bir resim dosyasını alır.
  • Belirtilen genişlik, yükseklik, kalite ve format parametrelerine göre resmi işler.
  • Resmi, en-boy oranını bozmadan hedef width x height boyutlarına sığdırır. Kenarlarda kalan boşlukları (padding), PNG için şeffaf, diğer formatlar için (JPG, WebP, AVIF) beyaz renkle doldurur.
  • İşlenmiş resmi Django'nun MEDIA_ROOT ayarında belirtilen dizin altındaki processed/ klasörüne kaydeder.
  • Resmin meta verilerini (title, width, height, format, size, quality, slug, path vb.) PostImages modeline kaydeder.
• İstek Metodu: POST
• Content-Type: multipart/form-data
• Parametreler (Form Data):
  • image: (File) Yüklenecek resim dosyası.
  • title: (string, max_length=254) Resim için bir başlık.
  • width: (integer) İşlenmiş resmin hedef genişliği (piksel).
  • height: (integer) İşlenmiş resmin hedef yüksekliği (piksel).
  • quality: (integer, 1-100, varsayılan: 85) JPG ve WebP gibi kayıplı formatlar için resmin sıkıştırma kalitesi. Daha düşük değerler dosya boyutunu azaltır.
  • format: (string, seçimler: png, webp, jpg, avif, varsayılan: webp) Çıktı resminin dosya formatı. webp ve avif genellikle daha iyi sıkıştırma sunar.
• Başarılı Yanıt (HTTP 201 Created):

  {
      "id": 1,
      "title": "Yuklenen Resim Basligi",
      "path": "processed/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.webp",
      "processed_path": "original_image_name.jpg",
      "original_filename": "original_image_name.jpg",
      "format": "webp",
      "width": 800,
      "height": 600,
      "size": 123456,
      "quality": 85,
      "slug": "yuklenen-resim-basligi",
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:00:00Z",
      "is_active": true,
      "is_front": true
  }
  

• Değiştirilen/Oluşturulan Dosyalar:
  • image/serializers.py: PostImageCreateSerializer ve PostImagesSerializer tanımlandı.
  • image/views.py: ImageUploadView eklendi.
  • image/urls.py: upload/ URL deseni eklendi.
  • core/urls.py: image uygulaması URL'leri /api/v1/images/ altında dahil edildi.

---

2. Resim İndirme API Endpoint'i

Bu endpoint, önceden işlenmiş bir resmi slug'ını kullanarak doğrudan indirmek için kullanılır.

• Endpoint: GET /api/v1/images/<slug>/download/
  • <slug>: İndirilmek istenen resmin benzersiz slug değeri. Bu değer, yükleme endpoint'inden dönen yanıtta bulunur.
• İşlevsellik:
  • URL'den alınan slug değerine sahip PostImages nesnesini veritabanından bulur.
  • İlişkili resim dosyasını sunucudan okur.
  • Resmi, tarayıcının indirme işlemi başlatmasını sağlayacak uygun HTTP başlıkları (Content-Type, Content-Disposition) ile bir FileResponse olarak gönderir.
• İstek Metodu: GET
• Başarılı Yanıt (HTTP 200 OK): Doğrudan resim dosyası içeriği döner, tarayıcı tarafından indirme işlemi başlatılır.
• Hata Durumları (HTTP 404 Not Found): Belirtilen slug ile resim bulunamazsa veya dosya sunucuda yoksa.
• Değiştirilen Dosyalar:
  • image/views.py: ImageDownloadView eklendi.
  • image/urls.py: <slug>/download/ URL deseni eklendi.

---

3. Model Silindiğinde Otomatik Dosya Silme

Bu özellik, PostImages modelinden bir kayıt silindiğinde, ilişkili resim dosyasının sunucudan otomatik olarak kaldırılmasını sağlar.

• İşlevsellik:
  • Django admin panelinden veya kod aracılığıyla bir PostImages nesnesi silindiğinde, Django'nun post_delete sinyali yakalanır.
  • Bu sinyal tetiklendiğinde, silinen PostImages nesnesinin path alanında belirtilen dosya yolu kullanılarak MEDIA_ROOT dizinindeki ilgili resim dosyası silinir.
• Mekanizma: Django Sinyalleri
• Değiştirilen/Oluşturulan Dosyalar:
  • image/signals.py (Yeni dosya): post_delete alıcısı (delete_image_file fonksiyonu) tanımlandı.
  • image/apps.py: Uygulama başlatıldığında image.signals'i içe aktarmak için ready() metodu güncellendi.
  • core/settings.py: INSTALLED_APPS listesindeki 'image' girdisi, 'image.apps.ImageConfig' olarak değiştirilerek sinyal mekanizmasının doğru şekilde çalışması sağlandı.

---

Not: Bu değişikliklerin geçerli olması için Django geliştirme sunucunuzu yeniden başlatmanız gerekebilir. Ayrıca, settings.py dosyasında MEDIA_ROOT ve MEDIA_URL ayarlarının doğru yapıldığından emin olun.