gobeyhan/api_documentation.md

# 🚀 Backend API Dokümantasyonu

## 📋 İçindekiler

- [Genel Bilgiler](#genel-bilgiler)
- [Swagger UI](#swagger-ui)
- [Authentication](#authentication)
- [Response Formatı](#response-formatı)
- [Hata Kodları](#hata-kodları)
- [Modüler Yapı](#modüler-yapı)
- [Endpoint'ler](#endpointler)
  - [Blog App](#blog-app)
  - [Account App](#account-app)
  - [Settings App](#settings-app)

---

## Genel Bilgiler

### Base URL
```
http://localhost:8080/api/v1
```

### Content Type
```
Content-Type: application/json
```

### Modüler Yapı
API, **app-based modüler yapı** kullanır:

| App | Sorumluluk | Endpoint Prefix |
|-----|------------|-----------------|
| **Blog** | Kategori, Tag, Post, Yorum | `/api/v1/categories`, `/api/v1/posts` |
| **Account** | Kullanıcı, Rol, İzin | `/api/v1/admin/users`, `/api/v1/admin/roles` |
| **Settings** | CORS, Rate Limit | `/api/v1/admin/cors`, `/api/v1/admin/rate-limits` |

---

## Swagger UI

### Swagger Dokümantasyonu

API'nin interaktif dokümantasyonuna Swagger UI üzerinden erişebilirsiniz:

```
http://localhost:8080/swagger/index.html
```

### Swagger Generate

Swagger dokümantasyonunu güncellemek için:

```bash
# Swagger docs oluştur
swag init

# Veya make komutu ile (varsa)
make swagger
```

### Swagger Annotation Örneği

Handler'larda godoc annotation'lar kullanılır:

```go
// GetAllCategories godoc
// @Summary Get all active categories
// @Description Get list of all active categories
// @Tags blog,categories
// @Accept json
// @Produce json
// @Success 200 {array} models.Category
// @Router /api/v1/categories [get]
func (h *CategoryHandler) GetAllCategories(c *gin.Context) {
    // ...
}
```

---

## Authentication

### Kimlik Doğrulama

Admin ve korumalı endpoint'ler için JWT token:

```http
Authorization: Bearer <your_jwt_token>
```

### Erişim Seviyeleri

| Seviye | Açıklama | Örnek |
|--------|----------|-------|
| 🌍 **Public** | Kimlik doğrulama gerektirmez | `GET /api/v1/posts` |
| 🔓 **Auth** | Login olmuş kullanıcı | `POST /api/v1/user/posts/:id/comments` |
| 🔐 **Admin** | Admin rolü gerekli | `POST /api/v1/admin/categories` |

---

## Response Formatı

### Başarılı Response

#### Tekil Kayıt
```json
{
  "data": {
    "id": 1,
    "title": "Örnek"
  }
}
```

#### Liste (Pagination ile)
```json
{
  "data": [...],
  "total": 100,
  "page": 1,
  "limit": 10
}
```

### Hata Response

```json
{
  "error": "Resource not found"
}
```

---

## Hata Kodları

| HTTP Status | Açıklama |
|-------------|----------|
| **200** | Başarılı |
| **201** | Oluşturuldu |
| **400** | Hatalı Request |
| **401** | Yetkisiz |
| **403** | Yasak |
| **404** | Bulunamadı |
| **500** | Sunucu Hatası |

---

## Modüler Yapı

### Kod Organizasyonu

```
app/
├── blog/          → Blog işlevleri
│   ├── handlers/
│   └── services/
├── account/       → Kullanıcı yönetimi
│   ├── handlers/
│   └── services/
└── settings/      → Sistem ayarları
    ├── handlers/
    └── services/
```

### Import Path'leri

```go
import (
    blogHandlers "gobeyhan/app/blog/handlers"
    blogServices "gobeyhan/app/blog/services"
    accountHandlers "gobeyhan/app/account/handlers"
    accountServices "gobeyhan/app/account/services"
)
```

---

## Endpoint'ler

## Blog App

Blog uygulaması 5 ana kaynak içerir: Categories, Tags, Posts, Comments, CategoryViews

### 📌 Categories

#### Tüm Kategoriler (Public)

```http
GET /api/v1/categories
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "title": "Teknoloji",
      "slug": "teknoloji",
      "parent": null,
      "children": [...]
    }
  ]
}
```

#### Kategori Detay (Public)

```http
GET /api/v1/categories/:slug
```

#### Kategori Görüntülenme (Public)

```http
POST /api/v1/categories/:id/view
```

#### Admin: Kategori CRUD

```http
GET    /api/v1/admin/categories
GET    /api/v1/admin/categories/:id
POST   /api/v1/admin/categories
PUT    /api/v1/admin/categories/:id
DELETE /api/v1/admin/categories/:id
GET    /api/v1/admin/categories/:id/views
```

**Create Request:**
```json
{
  "title": "Yeni Kategori",
  "slug": "yeni-kategori",
  "description": "Açıklama",
  "is_active": true,
  "order": 1,
  "parent_id": null
}
```

---

### 📌 Tags

#### Tüm Etiketler (Public)

```http
GET /api/v1/tags
```

#### Etiket Detay (Public)

```http
GET /api/v1/tags/:slug
```

#### Admin: Etiket CRUD

```http
GET    /api/v1/admin/tags
GET    /api/v1/admin/tags/:id
POST   /api/v1/admin/tags
PUT    /api/v1/admin/tags/:id
DELETE /api/v1/admin/tags/:id
```

**Create Request:**
```json
{
  "tag": "golang",
  "slug": "golang",
  "is_active": true
}
```

---

### 📌 Posts

#### Tüm Yazılar (Public, Paginated)

```http
GET /api/v1/posts?page=1&limit=10
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "title": "Blog Yazısı",
      "slug": "blog-yazisi",
      "user": {...},
      "categories": [...],
      "tags": [...]
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 10
}
```

#### Yazı Detay (Public)

```http
GET /api/v1/posts/:slug
```

#### Admin: Yazı CRUD

```http
GET    /api/v1/admin/posts
GET    /api/v1/admin/posts/:id
POST   /api/v1/admin/posts
PUT    /api/v1/admin/posts/:id
DELETE /api/v1/admin/posts/:id
```

**Create Request:**
```json
{
  "title": "Yeni Yazı",
  "content": "İçerik...",
  "categories": [1, 2],
  "tags": [1, 3, 5],
  "is_active": true
}
```

---

### 📌 Comments

#### Yazı Yorumları (Public)

```http
GET /api/v1/posts/:id/comments
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "user_id": 2,
      "body": "Yorum içeriği",
      "parent_id": null,
      "children": [...]
    }
  ]
}
```

#### Yorum Yaz (Auth)

```http
POST /api/v1/user/posts/:id/comments
Authorization: Bearer <token>
```

**Request:**
```json
{
  "body": "Yorum içeriği",
  "parent_id": null
}
```

#### Admin: Yorum Yönetimi

```http
GET    /api/v1/admin/comments
GET    /api/v1/admin/comments/:id
PUT    /api/v1/admin/comments/:id
DELETE /api/v1/admin/comments/:id
```

---

## Account App

Kullanıcı, rol ve izin yönetimi

### 📌 Users

#### Admin: Tüm Kullanıcılar

```http
GET /api/v1/admin/users?page=1&limit=10&include_deleted=false
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "roles": [...],
      "social_accounts": [...],
      "deleted_at": null
    }
  ],
  "total": 50
}
```

#### Admin: Kullanıcı CRUD

```http
GET    /api/v1/admin/users/:id
POST   /api/v1/admin/users
PUT    /api/v1/admin/users/:id
DELETE /api/v1/admin/users/:id        # Soft delete
POST   /api/v1/admin/users/:id/restore
```

**Create Request:**
```json
{
  "email": "user@example.com",
  "password": "securePass123",
  "username": "newuser"
}
```

> **Not**: Password bcrypt ile hashlenip saklanır

#### Admin: Rol Yönetimi

```http
POST   /api/v1/admin/users/:id/roles
DELETE /api/v1/admin/users/:id/roles/:role_id
```

**Assign Role:**
```json
{
  "role_id": 2
}
```

---

### 📌 Roles

#### Admin: Roller

```http
GET    /api/v1/admin/roles
GET    /api/v1/admin/roles/:id
POST   /api/v1/admin/roles
PUT    /api/v1/admin/roles/:id
DELETE /api/v1/admin/roles/:id
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "admin",
      "description": "Administrator",
      "permissions": [...]
    }
  ]
}
```

**Create Request:**
```json
{
  "name": "moderator",
  "description": "Moderator role"
}
```

---

### 📌 Permissions

#### Admin: İzinler

```http
GET  /api/v1/admin/permissions
POST /api/v1/admin/permissions
```

**Create Request:**
```json
{
  "name": "edit_comment",
  "description": "Can edit comments"
}
```

---

### 📌 Social Accounts

#### Auth: Kullanıcının Social Hesapları

```http
GET    /api/v1/user/social-accounts
DELETE /api/v1/user/social-accounts/:id
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "provider": "google",
      "provider_user_id": "123456"
    }
  ]
}
```

---

## Settings App

Sistem ayarları ve yapılandırma

### 📌 CORS Whitelist

#### Admin: CORS Whitelist

```http
GET    /api/v1/admin/cors/whitelist
POST   /api/v1/admin/cors/whitelist
PUT    /api/v1/admin/cors/whitelist/:id
DELETE /api/v1/admin/cors/whitelist/:id
```

**Create Request:**
```json
{
  "origin": "https://example.com",
  "description": "Main website"
}
```

---

### 📌 CORS Blacklist

```http
GET    /api/v1/admin/cors/blacklist
POST   /api/v1/admin/cors/blacklist
PUT    /api/v1/admin/cors/blacklist/:id
DELETE /api/v1/admin/cors/blacklist/:id
```

---

### 📌 Rate Limits

#### Admin: Rate Limit Ayarları

```http
GET /api/v1/admin/rate-limits
PUT /api/v1/admin/rate-limits/:id
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "path": "/api/v1/posts",
      "max_requests": 100,
      "window_seconds": 60
    }
  ]
}
```

**Update Request:**
```json
{
  "max_requests": 200,
  "window_seconds": 120
}
```

---

### 📌 CORS Cache

#### Admin: Cache Temizle

```http
POST /api/v1/admin/cors/cache/invalidate
```

---

## Endpoint Özeti

### Blog App (29 endpoint)

| Kaynak | Public | Auth | Admin |
|--------|--------|------|-------|
| Categories | 3 | 0 | 6 |
| Tags | 2 | 0 | 5 |
| Posts | 2 | 0 | 5 |
| Comments | 1 | 1 | 4 |
| CategoryViews | 1 | 0 | 1 |

### Account App (17 endpoint)

| Kaynak | Public | Auth | Admin |
|--------|--------|------|-------|
| Users | 0 | 0 | 8 |
| Roles | 0 | 0 | 5 |
| Permissions | 0 | 0 | 2 |
| Social Accounts | 0 | 2 | 0 |

### Settings App (11 endpoint)

| Kaynak | Public | Auth | Admin |
|--------|--------|------|-------|
| CORS Whitelist | 0 | 0 | 4 |
| CORS Blacklist | 0 | 0 | 4 |
| Rate Limits | 0 | 0 | 2 |
| Cache | 0 | 0 | 1 |

**TOPLAM: 57 endpoint**

---

## cURL Örnekleri

### Public Endpoint
```bash
curl http://localhost:8080/api/v1/posts?page=1&limit=5
```

### Admin Endpoint
```bash
curl -X POST http://localhost:8080/api/v1/admin/categories \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test"}'
```

### Authentication Endpoints

### Register
**POST** `/api/v1/auth/register`
Create a new user account.

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "securePass123",
  "username": "johndoe"
}
```

**Response:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "avatar": "",
    "created_at": "2024-03-20T10:00:00Z"
  }
}
```

### Login
**POST** `/api/v1/auth/login`
Authenticate user and get JWT token.

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "securePass123"
}
```

**Response:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { ... }
}
```

### OAuth Login (Google)
**GET** `/api/v1/auth/google`
Redirects to Google OAuth login page.

**Callback:** `/api/v1/auth/google/callback`
Exchanges code for token and returns JWT + User.

### OAuth Login (GitHub)
**GET** `/api/v1/auth/github`
Redirects to GitHub OAuth login page.

**Callback:** `/api/v1/auth/github/callback`
Exchanges code for token and returns JWT + User.

### Logout
**POST** `/api/v1/auth/logout`
Logout user (client-side token removal recommended).

---

## Blog Endpoints
```bash
curl -X POST http://localhost:8080/api/v1/user/posts/1/comments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"body": "Great post!"}'
```

---

## Postman Collection

Environment variables:
```json
{
  "base_url": "http://localhost:8080/api/v1",
  "admin_token": "eyJhbGc...",
  "user_token": "eyJhbGc..."
}
```

---

## Middleware Notları

Auth ve Admin middleware'ler şu anda yorumda:

**Aktif etmek için** [routes.go](file:///Users/beyhan/Desktop/Projeler/Go/gobeyhan/app/routes/routes.go):

```go
// Auth routes
user := api.Group("/user")
user.Use(AuthMiddleware())

// Admin routes  
admin := api.Group("/admin")
admin.Use(AuthMiddleware(), AdminMiddleware())
```

---

## Swagger Entegrasyonu

### Kurulum

```bash
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
```

### Generate

```bash
swag init
```

### Erişim

```
http://localhost:8080/swagger/index.html
```

---

**Last Updated:** 2026-02-11  
**Version:** 2.0 (Modular Structure)