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:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Request Örneği (cURL):

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):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000",
  "token_type": "bearer"
}

Response (400 Bad Request):

{
  "error": "invalid input: email: Email validation failed"
}

Response (409 Conflict - Email zaten kayıtlı):

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

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Request Örneği (cURL):

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):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000",
  "token_type": "bearer"
}

Response (401 Unauthorized):

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

# 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):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000"
}

Response (400 Bad Request):

{
  "error": "missing code"
}

Response (500 Internal Server Error):

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

curl http://localhost:3000/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "provider": null
}

OAuth ile kayıt olmuş kullanıcı için:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@gmail.com",
  "provider": "google"
}

Response (401 Unauthorized - Geçersiz token):

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

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

# 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

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

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