Değerlendirme ve Puanlama Sistemi (Reviews API) Dokümantasyonu

Bu doküman, reviews uygulaması tarafından sağlanan API endpoint'lerinin frontend tarafında nasıl kullanılacağını açıklar. Bu sistem polimorfik bir yapıdadır, yani sadece ürünler için değil, ileride eklenebilecek diğer modüller (Blog, Satıcı vb.) için de kullanılabilir.

1. Genel Bilgiler

Base URL: /api/v1/reviews/
Authentication: Oy verme işlemi (POST) için kullanıcının giriş yapmış olması (Token ile) gerekir. Listeleme (GET) işlemi herkese açıktır.

2. Ürün Verisinde Puanlama Bilgisi

Ürünleri listelediğinizde (/api/v1/products/) veya detayını çektiğinizde (/api/v1/products/<slug>/), ürün objesi artık şu iki alanı içerir:

average_rating (Float): Ürünün ortalama puanı (1.0 - 5.0 arası). Hiç oy yoksa 0.0 döner.
rating_count (Integer): Toplam kaç kişinin oy verdiği.

Örnek Ürün Objesi:

{
    "id": 15,
    "title": "Örnek Ürün",
    "price": 100.0,
    "average_rating": 4.5,  // <-- Ortalama Puan
    "rating_count": 12,     // <-- Oy Sayısı
    "images": "/media/uploads/products/example.avif",
    ...
}

Bu bilgileri ürün kartlarında yıldız göstermek için kullanabilirsiniz.

3. API Endpoint'leri

3.1. Oy Verme ve Yorum Yapma

Kullanıcının bir nesneye (örneğin bir ürüne) puan vermesini ve isteğe bağlı olarak yorum yapmasını sağlar. Bir kullanıcı aynı nesneye sadece bir kez oy verebilir; ikinci istekte mevcut oy güncellenir.

URL: /api/v1/reviews/rate/
Method: POST
Permission: IsAuthenticated (Header'da Authorization: Bearer <token> olmalı)

İstek (Request) Body Parametreleri:

Parametre	Tip	Zorunlu	Açıklama
`model_name`	String	Evet	Oylanacak nesnenin model adı. Örn: `"product"`
`object_id`	Integer	Evet	Oylanacak nesnenin ID'si. Örn: `15`
`score`	Integer	Evet	1 ile 5 arasında bir tam sayı.
`comment`	String	Hayır	Kullanıcının yorumu.

Örnek İstek (JSON):

{
  "model_name": "product",
  "object_id": 15,
  "score": 5,
  "comment": "Ürün beklediğimden çok daha kaliteli çıktı, tavsiye ederim."
}

Başarılı Yanıt (201 Created veya 200 OK):

{
  "id": 42,
  "score": 5,
  "comment": "Ürün beklediğimden çok daha kaliteli çıktı, tavsiye ederim.",
  "user": "kullanici_adi",
  "created_at": "2023-10-27T10:00:00Z",
  "model_name": "product",
  "object_id": 15
}

Hata Yanıtları:

400 Bad Request: Eksik parametre veya geçersiz puan (1-5 dışı).
401 Unauthorized: Giriş yapılmamış.
404 Not Found: Belirtilen model veya ID bulunamadı.

3.2. Değerlendirmeleri Listeleme

Belirli bir nesneye ait tüm yorumları ve puanları listeler. Genellikle ürün detay sayfasının altındaki "Yorumlar" sekmesinde kullanılır.

URL: /api/v1/reviews/list/
Method: GET
Permission: AllowAny (Herkes erişebilir)

Query Parametreleri:

Parametre	Zorunlu	Açıklama
`model`	Evet	Listelenecek nesnenin model adı. Örn: `product`
`id`	Evet	Listelenecek nesnenin ID'si.

Örnek İstek:

GET /api/v1/reviews/list/?model=product&id=15

Başarılı Yanıt (200 OK):

[
  {
    "id": 42,
    "score": 5,
    "comment": "Harika ürün!",
    "user": "ahmet123",
    "created_at": "2023-10-27T10:00:00Z",
    "model_name": "product",
    "object_id": 15
  },
  {
    "id": 43,
    "score": 4,
    "comment": "Kargo biraz geç geldi ama ürün güzel.",
    "user": "ayse_yilmaz",
    "created_at": "2023-10-26T14:30:00Z",
    "model_name": "product",
    "object_id": 15
  }
]

4. Frontend Entegrasyon Senaryosu (React Örneği)

Bir ürün detay sayfasında (Product Detail Page) yapılması gerekenler:

Ürün Bilgisini Çek: /api/v1/products/<slug>/ endpoint'inden ürünü çekin. Gelen average_rating ve rating_count ile sayfanın üst kısmında yıldızları gösterin.
Yorumları Çek: Ürün ID'sini kullanarak /api/v1/reviews/list/?model=product&id=<id> endpoint'inden yorumları çekin ve aşağıda listeleyin.

import React, { useState, useEffect } from 'react';
import axios from 'axios';

function ProductDetail({ slug }) {
  const [product, setProduct] = useState(null);
  const [reviews, setReviews] = useState([]);

  useEffect(() => {
    async function fetchData() {
      // 1. Ürün detayını çek
      const prodRes = await axios.get(`/api/v1/products/${slug}/`);
      setProduct(prodRes.data);

      // 2. Ürünün yorumlarını çek (prodRes.data.id kullanarak)
      const reviewRes = await axios.get(`/api/v1/reviews/list/`, {
        params: { model: 'product', id: prodRes.data.id }
      });
      setReviews(reviewRes.data);
    }
    fetchData();
  }, [slug]);

  if (!product) return <div>Yükleniyor...</div>;

  return (
    <div>
      <h1>{product.title}</h1>
      
      {/* Özet Puan Gösterimi */}
      <div className="rating-summary">
        <span>Ortalama Puan: {product.average_rating} / 5</span>
        <span>({product.rating_count} değerlendirme)</span>
      </div>

      {/* ... Ürün detayları ... */}

      {/* Yorumlar Listesi */}
      <div className="reviews-section">
        <h3>Yorumlar</h3>
        {reviews.map(review => (
          <div key={review.id} className="review-card">
            <strong>{review.user}</strong> - <span>{review.score} Yıldız</span>
            <p>{review.comment}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

5. Notlar

Resim Yolları: API'den dönen resim yolları /media/... şeklinde olabilir. Frontend tarafında base URL'i (http://localhost:8000 veya canlı sunucu adresi) başına eklemeniz gerekebilir.

6.3 KiB Raw Blame History Unescape Escape