beyhan/gobeyhan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
gobeyhan/api_documentation.md
Beyhan Oğur f34e54c5a5 first commit
2026-04-26 21:43:40 +03:00

12 KiB
Raw Permalink Blame History

🚀 Backend API Dokümantasyonu

📋 İçindekiler

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:

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

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

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

{
  "data": {
    "id": 1,
    "title": "Örnek"
  }
}

Liste (Pagination ile)

{
  "data": [...],
  "total": 100,
  "page": 1,
  "limit": 10
}

Hata Response

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

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)

GET /api/v1/categories

Response:

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

Kategori Detay (Public)

GET /api/v1/categories/:slug

Kategori Görüntülenme (Public)

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

Admin: Kategori CRUD

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:

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

📌 Tags

Tüm Etiketler (Public)

GET /api/v1/tags

Etiket Detay (Public)

GET /api/v1/tags/:slug

Admin: Etiket CRUD

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:

{
  "tag": "golang",
  "slug": "golang",
  "is_active": true
}

📌 Posts

Tüm Yazılar (Public, Paginated)

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

Response:

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

Yazı Detay (Public)

GET /api/v1/posts/:slug

Admin: Yazı CRUD

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:

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

📌 Comments

Yazı Yorumları (Public)

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

Response:

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

Yorum Yaz (Auth)

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

Request:

{
  "body": "Yorum içeriği",
  "parent_id": null
}

Admin: Yorum Yönetimi

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

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

Response:

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

Admin: Kullanıcı CRUD

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:

{
  "email": "user@example.com",
  "password": "securePass123",
  "username": "newuser"
}

Not: Password bcrypt ile hashlenip saklanır

Admin: Rol Yönetimi

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

Assign Role:

{
  "role_id": 2
}

📌 Roles

Admin: Roller

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:

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

Create Request:

{
  "name": "moderator",
  "description": "Moderator role"
}

📌 Permissions

Admin: İzinler

GET  /api/v1/admin/permissions
POST /api/v1/admin/permissions

Create Request:

{
  "name": "edit_comment",
  "description": "Can edit comments"
}

📌 Social Accounts

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

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

Response:

{
  "data": [
    {
      "id": 1,
      "provider": "google",
      "provider_user_id": "123456"
    }
  ]
}

Settings App

Sistem ayarları ve yapılandırma

📌 CORS Whitelist

Admin: CORS Whitelist

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:

{
  "origin": "https://example.com",
  "description": "Main website"
}

📌 CORS Blacklist

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ı

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

Response:

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

Update Request:

{
  "max_requests": 200,
  "window_seconds": 120
}

📌 CORS Cache

Admin: Cache Temizle

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

curl http://localhost:8080/api/v1/posts?page=1&limit=5

Admin Endpoint

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:

{
  "email": "user@example.com",
  "password": "securePass123",
  "username": "johndoe"
}

Response:

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

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

Response:

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

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:

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

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

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

Swagger Entegrasyonu

Kurulum

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

swag init

Erişim

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

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

Reference in New Issue View Git Blame Copy Permalink