RESTful API Tasarım Prensipleri ve Best Practices

REST API Nedir?

REST (Representational State Transfer), web servisleri için bir mimari stildir. HTTP protokolü üzerinden kaynaklara erişim sağlar.

HTTP Metodları

URL Yapılandırma

İyi Örnekler

GET    /api/v1/users              # Kullanıcı listesi
GET    /api/v1/users/123          # Tek kullanıcı
GET    /api/v1/users/123/orders   # Kullanıcının siparişleri
POST   /api/v1/users              # Yeni kullanıcı
PATCH  /api/v1/users/123          # Kullanıcı güncelle
DELETE /api/v1/users/123          # Kullanıcı sil

Kaçınılması Gerekenler

❌ GET /api/getUsers
❌ POST /api/createUser
❌ GET /api/users/delete/123
❌ GET /api/users?action=delete&id=123

Response Formatı

Başarılı Response

{
    "success": true,
    "data": {
        "id": 123,
        "name": "John Doe",
        "email": "[email protected]"
    },
    "meta": {
        "timestamp": "2025-01-15T10:30:00Z"
    }
}

Liste Response

{
    "success": true,
    "data": [...],
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 150,
        "last_page": 10
    },
    "links": {
        "first": "/api/users?page=1",
        "last": "/api/users?page=10",
        "prev": null,
        "next": "/api/users?page=2"
    }
}

Hata Response

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The given data was invalid.",
        "details": {
            "email": ["Email alanı gereklidir."],
            "password": ["Şifre en az 8 karakter olmalı."]
        }
    }
}

HTTP Status Codes

200 OK           - Başarılı GET, PUT, PATCH
201 Created      - Başarılı POST
204 No Content   - Başarılı DELETE
400 Bad Request  - Validation hatası
401 Unauthorized - Authentication gerekli
403 Forbidden    - Yetki yok
404 Not Found    - Kaynak bulunamadı
422 Unprocessable - Validation hatası (Laravel)
429 Too Many     - Rate limit aşıldı
500 Server Error - Sunucu hatası

API Versioning

URL Versioning (Önerilen)

/api/v1/users
/api/v2/users

Header Versioning

Accept: application/vnd.api+json;version=1

Authentication

Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Laravel Sanctum

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('users', UserController::class);
});

Rate Limiting

// Laravel
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

// Response headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1697234567

API Dokümantasyonu

• OpenAPI/Swagger: Standart API spec
• Postman: Collection paylaşımı
• Scribe: Laravel için otomatik doc

Sonuç

İyi tasarlanmış bir API, tutarlı, öngörülebilir ve kullanımı kolay olmalıdır. Bu prensipleri takip ederek, geliştiricilerin sevdiği API'lar oluşturabilirsiniz.