goaresv3/belgeler/api-referans.md

# API Referansı

Base URL: `http://localhost:8080`

---

## Public Endpoint'ler  
_Token gerektirmez._

---

### `POST /api/v1/auth/register`

Yeni kullanıcı oluşturur ve doğrulama maili gönderir.

**İstek gövdesi**
```json
{
  "username": "ali",
  "email":    "ali@ornek.com",
  "password": "gizli1234",
  "confirm_password": "gizli1234"
}
```

| Alan | Tip | Kural |
|---|---|---|
| `username` | string | Zorunlu, 3–50 karakter |
| `email` | string | Zorunlu, geçerli e-posta |
| `password` | string | Zorunlu, min 8 karakter |
| `confirm_password` | string | Zorunlu, `password` ile aynı olmalı |

**Yanıtlar**

| Durum | Açıklama | Gövde örneği |
|---|---|---|
| `201 Created` | Kayıt başarılı, doğrulama maili gönderildi | `{ "message": "user created. please verify your email", "user_id": 1 }` |
| `400 Bad Request` | Doğrulama hatası | `{ "error": "Key: 'RegisterRequest.Email' Error:..." }` |
| `400 Bad Request` | Şifreler eşleşmiyor | `{ "error": "password and confirm_password do not match" }` |
| `409 Conflict` | E-posta zaten kayıtlı | `{ "error": "email already in use" }` |
| `500 Internal Server Error` | Doğrulama maili gönderilemedi | `{ "error": "failed to send verification email" }` |

---

### `GET /api/v1/auth/verify-email`

Kullanıcı email doğrulama linkindeki token ile hesabı aktive eder.

**Query parametreleri**

| Alan | Tip | Kural |
|---|---|---|
| `token` | string | Zorunlu |

**Yanıtlar**

| Durum | Açıklama | Gövde örneği |
|---|---|---|
| `200 OK` | Email doğrulandı | `{ "message": "email verified successfully" }` |
| `400 Bad Request` | Token eksik/geçersiz | `{ "error": "invalid or expired verification token" }` |
| `500 Internal Server Error` | Sunucu hatası | `{ "error": "could not verify email" }` |

---

### `POST /api/v1/auth/login`

E-posta ve şifre ile giriş yapar; token çifti döner.

**İstek gövdesi**
```json
{
  "email":    "ali@ornek.com",
  "password": "gizli1234"
}
```

**Yanıtlar**

| Durum | Açıklama | Gövde örneği |
|---|---|---|
| `200 OK` | Giriş başarılı | Aşağıya bakın |
| `400 Bad Request` | Eksik alan | `{ "error": "..." }` |
| `401 Unauthorized` | Yanlış bilgi | `{ "error": "invalid email or password" }` |
| `403 Forbidden` | Email doğrulanmamış | `{ "error": "email is not verified" }` |

```json
// 200 OK
{
  "access_token":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type":    "Bearer"
}
```

---

### `POST /api/v1/auth/refresh`

Süresi dolmuş access token'ı yeniler.

**İstek gövdesi**
```json
{ "refresh_token": "eyJ..." }
```

**Yanıtlar**

| Durum | Açıklama | Gövde örneği |
|---|---|---|
| `200 OK` | Yenileme başarılı | `{ "access_token": "eyJ...", "token_type": "Bearer" }` |
| `400 Bad Request` | Eksik alan | `{ "error": "..." }` |
| `401 Unauthorized` | Token geçersiz/süresi dolmuş | `{ "error": "invalid or expired refresh token" }` |
| `403 Forbidden` | Email doğrulanmamış | `{ "error": "email is not verified" }` |

---

## Korumalı Endpoint'ler  
_`Authorization: Bearer <access_token>` başlığı zorunludur._

---

### `GET /api/v1/me`

Oturum açmış kullanıcının kimlik bilgilerini döner.

**İstek başlığı**
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Yanıtlar**

| Durum | Açıklama | Gövde örneği |
|---|---|---|
| `200 OK` | Başarılı | `{ "user_id": 1, "email": "ali@ornek.com", "username": "ali" }` |
| `401 Unauthorized` | Başlık eksik veya token geçersiz | `{ "error": "authorization header missing or malformed" }` |

---

## Admin Yetkisi Gerektiren Endpoint'ler

Bu endpointler için kullanıcı hem giriş yapmış olmalı hem de `is_admin=true` olmalıdır.

### Settings

- `PUT /api/v1/settings`
- `POST /api/v1/settings/heroes`
- `PUT /api/v1/settings/heroes/{id}`
- `DELETE /api/v1/settings/heroes/{id}`
- `POST /api/v1/settings/cors/whitelist`
- `PUT /api/v1/settings/cors/whitelist/{id}`
- `DELETE /api/v1/settings/cors/whitelist/{id}`
- `POST /api/v1/settings/cors/blacklist`
- `PUT /api/v1/settings/cors/blacklist/{id}`
- `DELETE /api/v1/settings/cors/blacklist/{id}`
- `POST /api/v1/settings/rate-limits`
- `PUT /api/v1/settings/rate-limits/{id}`
- `DELETE /api/v1/settings/rate-limits/{id}`

### Shop

- `POST /api/v1/shop/categories`
- `PUT /api/v1/shop/categories/{id}`
- `DELETE /api/v1/shop/categories/{id}`
- `POST /api/v1/shop/tags`
- `PUT /api/v1/shop/tags/{id}`
- `DELETE /api/v1/shop/tags/{id}`
- `POST /api/v1/shop/products`
- `PUT /api/v1/shop/products/{id}`
- `DELETE /api/v1/shop/products/{id}`

### Blog

- `POST /api/v1/blog/categories`
- `PUT /api/v1/blog/categories/{id}`
- `DELETE /api/v1/blog/categories/{id}`
- `POST /api/v1/blog/tags`
- `PUT /api/v1/blog/tags/{id}`
- `DELETE /api/v1/blog/tags/{id}`
- `POST /api/v1/blog/posts`
- `PUT /api/v1/blog/posts/{id}`
- `DELETE /api/v1/blog/posts/{id}`

---

## Auth Gerekli (Okuma / Kullanıcı İşlemleri)

### Settings (read)
- `GET /api/v1/settings`
- `GET /api/v1/settings/heroes`
- `GET /api/v1/settings/cors/whitelist`
- `GET /api/v1/settings/cors/blacklist`
- `GET /api/v1/settings/rate-limits`

### Shop
- `GET /api/v1/shop/categories`
- `GET /api/v1/shop/tags`
- `GET /api/v1/shop/products`
- `GET /api/v1/shop/products/{id}`
- `GET /api/v1/shop/cart`
- `POST /api/v1/shop/cart/items`
- `PUT /api/v1/shop/cart/items/{itemId}`
- `DELETE /api/v1/shop/cart/items/{itemId}`

### Blog
- `GET /api/v1/blog/categories`
- `GET /api/v1/blog/tags`
- `GET /api/v1/blog/posts`
- `GET /api/v1/blog/posts/{id}`

---

## Runtime Güvenlik Davranışı

- **CORS blacklist**: origin varsa doğrudan blok (`403`).
- **CORS whitelist**: origin whitelist'te ise rate-limit muaf.
- **Whitelist/blacklist dışı**: CORS geçer, rate-limit uygulanır.
- **Rate limit kural sırası**:
  1. Endpoint adı (`api/v1/auth/login` gibi)
  2. Fallback `api`

> En güncel endpoint listesi ve request/response şemaları için Swagger UI kullanın.

---

## Hata Formatı

Tüm hata yanıtları aynı yapıdadır:

```json
{ "error": "açıklayıcı hata mesajı" }
```

---

## curl Örnekleri

```bash
# Kayıt
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"ali","email":"ali@ornek.com","password":"gizli1234","confirm_password":"gizli1234"}'

# Email doğrulama
curl "http://localhost:8080/api/v1/auth/verify-email?token=<verification_token>"

# Giriş
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ali@ornek.com","password":"gizli1234"}'

# Korumalı endpoint
curl http://localhost:8080/api/v1/me \
  -H "Authorization: Bearer <access_token>"

# Token yenile
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<refresh_token>"}'
```

---

## Swagger

- UI: `http://localhost:8080/swagger/index.html`
- OpenAPI dosyaları: `docs/swagger.json`, `docs/swagger.yaml`