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

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

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

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

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

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

---

curl Örnekleri

# 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