RustApi/API_DOCUMENTATION.md

# 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.