first commit
This commit is contained in:
Beyhan Oğur
192
REVIEWS_API.md
Normal file
192
REVIEWS_API.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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:**
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
|
||||
```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):
|
||||
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:
|
||||
|
||||
1. **Ü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.
|
||||
2. **Yorumları Çek:** Ürün ID'sini kullanarak `/api/v1/reviews/list/?model=product&id=<id>` endpoint'inden yorumları çekin ve aşağıda listeleyin.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
Reference in New Issue
Block a user