first commit

2026-04-26 22:31:06 +03:00
commit 6e06119135
30 changed files with 1232 additions and 0 deletions
--- a/API_DOCUMENTATION.md
+++ b/API_DOCUMENTATION.md
@@ -0,0 +1,396 @@
+# Rust API Account System - API Dokümantasyonu
+
+## Genel Bilgiler
+
+**Base URL:** `http://localhost:3000/api/v1`  
+**Content-Type:** `application/json`  
+**Authentication:** Bearer Token (JWT)
+
+### Token Yapısı
+
+- **Access Token:** Kısa ömürlü JWT token (varsayılan: 15 dakika)
+- **Refresh Token:** Uzun ömürlü UUID token (varsayılan: 30 gün)
+- **Token Format:** `Bearer <access_token>`
+
+---
+
+## Authentication Endpoints
+
+### 1. Kullanıcı Kaydı
+
+Yeni bir kullanıcı hesabı oluşturur ve access/refresh token döner.
+
+**Endpoint:** `POST /api/v1/auth/register`
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securePassword123"
+}
+```
+
+**Request Örneği (cURL):**
+```bash
+curl -X POST http://localhost:3000/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "securePassword123"
+  }'
+```
+
+**Response (200 OK):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "550e8400-e29b-41d4-a716-446655440000",
+  "token_type": "bearer"
+}
+```
+
+**Response (400 Bad Request):**
+```json
+{
+  "error": "invalid input: email: Email validation failed"
+}
+```
+
+**Response (409 Conflict - Email zaten kayıtlı):**
+```json
+{
+  "error": "email already exists"
+}
+```
+
+**Validasyon Kuralları:**
+- `email`: Geçerli bir email formatı olmalı
+- `password`: Boş olmamalı
+
+---
+
+### 2. Kullanıcı Girişi
+
+Mevcut kullanıcı ile giriş yapar ve access/refresh token döner.
+
+**Endpoint:** `POST /api/v1/auth/login`
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securePassword123"
+}
+```
+
+**Request Örneği (cURL):**
+```bash
+curl -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "securePassword123"
+  }'
+```
+
+**Response (200 OK):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "550e8400-e29b-41d4-a716-446655440000",
+  "token_type": "bearer"
+}
+```
+
+**Response (401 Unauthorized):**
+```json
+{
+  "error": "invalid credentials"
+}
+```
+
+---
+
+### 3. OAuth Yönlendirme
+
+OAuth provider'a (Google/GitHub) yönlendirme URL'i oluşturur.
+
+**Endpoint:** `GET /api/v1/auth/oauth/{provider}`
+
+**Path Parameters:**
+- `provider`: `google` veya `github`
+
+**Request Örneği (cURL):**
+```bash
+# Google OAuth
+curl http://localhost:3000/api/v1/auth/oauth/google
+
+# GitHub OAuth
+curl http://localhost:3000/api/v1/auth/oauth/github
+```
+
+**Response:** 
+- HTTP 302 Redirect - Kullanıcıyı OAuth provider'a yönlendirir
+
+**Tarayıcı Kullanımı:**
+```
+http://localhost:3000/api/v1/auth/oauth/google
+http://localhost:3000/api/v1/auth/oauth/github
+```
+
+**Not:** Bu endpoint tarayıcıda açılmalıdır. OAuth akışı için kullanıcı etkileşimi gereklidir.
+
+---
+
+### 4. OAuth Callback
+
+OAuth provider'dan dönen authorization code'u token'a çevirir.
+
+**Endpoint:** `GET /api/v1/auth/oauth/{provider}/callback`
+
+**Path Parameters:**
+- `provider`: `google` veya `github`
+
+**Query Parameters:**
+- `code`: OAuth provider'dan dönen authorization code
+
+**Request Örneği:**
+```
+http://localhost:3000/api/v1/auth/oauth/google/callback?code=4/0AeanS...
+```
+
+**Response (200 OK):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+**Response (400 Bad Request):**
+```json
+{
+  "error": "missing code"
+}
+```
+
+**Response (500 Internal Server Error):**
+```json
+{
+  "error": "token exchange failed"
+}
+```
+
+**OAuth Akışı:**
+1. Kullanıcı `/api/v1/auth/oauth/{provider}` endpoint'ine yönlendirilir
+2. OAuth provider'da giriş yapar ve izin verir
+3. Provider, `{OAUTH_REDIRECT_BASE}/api/v1/auth/oauth/{provider}/callback?code=...` adresine yönlendirir
+4. Callback endpoint authorization code'u token'a çevirir ve döner
+
+---
+
+## User Endpoints
+
+### 5. Kullanıcı Bilgileri
+
+Mevcut kullanıcının bilgilerini döner. Access token gereklidir.
+
+**Endpoint:** `GET /api/v1/users/me`
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Request Örneği (cURL):**
+```bash
+curl http://localhost:3000/api/v1/users/me \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Response (200 OK):**
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "email": "user@example.com",
+  "provider": null
+}
+```
+
+**OAuth ile kayıt olmuş kullanıcı için:**
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "email": "user@gmail.com",
+  "provider": "google"
+}
+```
+
+**Response (401 Unauthorized - Geçersiz token):**
+```json
+{
+  "id": "",
+  "email": "",
+  "provider": null
+}
+```
+
+---
+
+## Hata Kodları
+
+| HTTP Status | Açıklama |
+|-------------|----------|
+| 200 OK | İstek başarılı |
+| 302 Found | OAuth yönlendirme |
+| 400 Bad Request | Geçersiz istek (validasyon hatası, eksik parametre) |
+| 401 Unauthorized | Yetkilendirme hatası (geçersiz token, yanlış şifre) |
+| 409 Conflict | Email zaten kayıtlı |
+| 500 Internal Server Error | Sunucu hatası |
+
+---
+
+## Örnek Kullanım Senaryoları
+
+### Senaryo 1: Email/Password ile Kayıt ve Giriş
+
+```bash
+# 1. Kayıt ol
+curl -X POST http://localhost:3000/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "password": "mypassword123"
+  }'
+
+# Response'dan access_token ve refresh_token'ı al
+
+# 2. Kullanıcı bilgilerini getir
+curl http://localhost:3000/api/v1/users/me \
+  -H "Authorization: Bearer <access_token>"
+
+# 3. Giriş yap (token süresi dolduğunda)
+curl -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "password": "mypassword123"
+  }'
+```
+
+### Senaryo 2: Google OAuth ile Giriş
+
+```bash
+# 1. Tarayıcıda şu URL'i aç:
+# http://localhost:3000/api/v1/auth/oauth/google
+
+# 2. Google'da giriş yap ve izin ver
+
+# 3. Callback URL'den dönen access_token ve refresh_token'ı kullan
+
+# 4. Kullanıcı bilgilerini getir
+curl http://localhost:3000/api/v1/users/me \
+  -H "Authorization: Bearer <access_token>"
+```
+
+### Senaryo 3: JavaScript/Fetch ile Kullanım
+
+```javascript
+// Kayıt
+async function register(email, password) {
+  const response = await fetch('http://localhost:3000/api/v1/auth/register', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ email, password }),
+  });
+  return await response.json();
+}
+
+// Giriş
+async function login(email, password) {
+  const response = await fetch('http://localhost:3000/api/v1/auth/login', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ email, password }),
+  });
+  return await response.json();
+}
+
+// Kullanıcı bilgileri
+async function getMe(accessToken) {
+  const response = await fetch('http://localhost:3000/api/v1/users/me', {
+    headers: {
+      'Authorization': `Bearer ${accessToken}`,
+    },
+  });
+  return await response.json();
+}
+
+// Kullanım
+const { access_token, refresh_token } = await register('user@example.com', 'password123');
+const userInfo = await getMe(access_token);
+console.log(userInfo);
+```
+
+---
+
+## Güvenlik Notları
+
+1. **HTTPS Kullanımı:** Production ortamında mutlaka HTTPS kullanın
+2. **Token Saklama:** Access token'ları güvenli bir şekilde saklayın (localStorage yerine httpOnly cookie tercih edilir)
+3. **Token Yenileme:** Access token süresi dolduğunda refresh token kullanarak yeni token alın
+4. **Şifre Güvenliği:** Şifreler SHA-256 ile ön-hash edilip sonra bcrypt ile hash'lenir
+5. **Rate Limiting:** Production'da rate limiting ekleyin
+6. **CORS:** Frontend uygulamanız için CORS ayarlarını yapılandırın
+
+---
+
+## Environment Variables
+
+API'nin çalışması için gerekli environment değişkenleri:
+
+```env
+# Database
+DATABASE_URL=postgres://user:password@localhost:5432/dbname
+
+# JWT Secret
+SECRET_KEY=your-secret-key-here-min-32-chars
+
+# Token Süreleri
+ACCESS_TOKEN_EXPIRE_MINUTES=15
+REFRESH_TOKEN_EXPIRE_DAYS=30
+
+# OAuth - Google
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# OAuth - GitHub
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# OAuth Redirect Base URL
+OAUTH_REDIRECT_BASE=http://localhost:3000
+
+# Server
+SERVER_HOST=127.0.0.1
+SERVER_PORT=3000
+```
+
+---
+
+## Notlar
+
+- Tüm endpoint'ler `/api/v1` prefix'i altındadır
+- Access token'lar JWT formatındadır ve `sub` (subject/user ID) ve `exp` (expiration) claim'lerini içerir
+- OAuth ile kayıt olan kullanıcıların `hashed_password` alanı NULL olur ve `provider` alanı set edilir
+- Refresh token endpoint'i henüz implement edilmemiştir (TODO)
+
+---
+
+## Destek
+
+Sorularınız için issue açabilir veya dokümantasyonu güncelleyebilirsiniz.