İyi Bir REST API Nasıl Tasarlanır? Pratik Rehber

İyi bir REST API şaşırtmaz. Geliştirici dokümana bakmadan yolu tahmin edebilir, sunucu kodunu okumadan yanıtı anlayabilir ve hatayı deneme yanılma olmadan çözebilir. Bu kalite, tutarlı kararlar ve açık bir sözleşmeyle oluşur.

İyi bir REST API’nin özellikleri

Güçlü bir API iş kaynaklarını açıkça modeller, HTTP semantiğine uyar, tutarlı JSON üretir, işe yarar hatalar döndürür, veriyi korur ve mevcut istemcileri bozmadan gelişir.

1. Kaynakları isimlerle modelleyin

orders, customers ve invoices gibi kararlı kavramlar kullanın. Çoğul isimleri ve /orders/42/items gibi yolları /getOrderItems biçimine tercih edin. Yetkilendirme ve bakım için iç içe yolları sığ tutun.

GET    /api/v1/orders
POST   /api/v1/orders
GET    /api/v1/orders/42
PATCH  /api/v1/orders/42
DELETE /api/v1/orders/42

2. HTTP yöntemlerinin anlamına uyun

GET durumu değiştirmeden okur; POST oluşturur veya idempotent olmayan işi başlatır; PUT kaynağı değiştirir; PATCH kısmen günceller; DELETE siler. RFC 9110 uyumu istemci, önbellek ve araçların doğru çalışmasını sağlar.

3. Doğru durum kodlarını döndürün

Başarı için 200, oluşturma için 201 ve Location, gövdesiz başarı için 204 kullanın. 400, 401, 403, 404, 409, 422 ve 429 durumlarını ayırın. 5xx kodları sunucu arızaları içindir.

4. JSON biçimini tutarlı tutun

Alan adları, tarihler, para, null değerleri ve zarf yapısı için tek standart seçin. Saat dilimiyle ISO 8601 kullanın. Veritabanı sütunlarını yanlışlıkla yayınlamayın; yanıtınız genel bir sözleşmedir.

{
  "data": {
    "id": 42,
    "status": "paid",
    "total": 129.90,
    "currency": "USD"
  }
}

5. Yararlı hatalar tasarlayın

Sabit tür veya kod, kısa başlık, HTTP durumu, güvenli açıklama, alan hataları ve istek kimliği ekleyin. RFC 9457 Problem Details standart bir biçim sunar.

{
  "type": "https://api.example.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": {"email": ["The email field is required."]}
}

6. Koleksiyonları standartlaştırın

?status=paid&sort=-created_at&page=2&per_page=25 gibi açık parametreler kullanın. Filtre ve sıralama alanlarını belgeleyin, maksimum sayfa boyutu belirleyin. Büyük veya hızla değişen veri için cursor pagination daha güvenlidir.

7. Uyumluluk ve sürümleme planlayın

Yeni isteğe bağlı alanlar çoğunlukla güvenlidir; alan adını veya türünü değiştirmek ve davranış silmek kırıcıdır. /api/v1 gibi açık bir strateji, kullanımdan kaldırma süresi ve geçiş notları yayınlayın.

8. Güvenliği sözleşmeye yerleştirin

HTTPS zorunlu olsun; her kaynak işlemini doğrulayın ve yetkilendirin. İzin listeleriyle girdi kontrolü, boyut ve hız sınırları uygulayın. Gizli bilgi veya stack trace döndürmeyin. Güvenlik olaylarını kimlik bilgileri ve kişisel veri olmadan kaydedin.

9. Önbellek ve eşzamanlılık

Güvenli okumalarda Cache-Control, ETag ve koşullu istekler kullanın. Sessiz üzerine yazmayı önlemek için If-Match veya sürüm değeri kabul edin. Idempotency key, ödeme ve oluşturma tekrarlarını güvenli kılar.

10. Dokümante edin ve test edin

Başarı, doğrulama, kimlik doğrulama ve rate-limit örnekleri içeren bir OpenAPI sözleşmesi tutun. Doküman, SDK, şema doğrulama ve contract test üretin. Korelasyon kimliği, yapılandırılmış log, metrik ve tracing ekleyin.

Laravel ile temiz REST API

Route::apiResource geleneksel CRUD yollarını oluşturur; Sanctum kimlik doğrular ve throttle middleware uç noktaları korur.

use App\Http\Controllers\Api\OrderController;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')
    ->middleware(['auth:sanctum', 'throttle:api'])
    ->group(function () {
        Route::apiResource('orders', OrderController::class);
    });

Doğrulama ve yetki için Form Request, kaynak izinleri için Policy, JSON sözleşmesi için API Resource kullanın. Controller HTTP akışında kalsın; karmaşık iş mantığını servis veya action sınıflarına taşıyın.

public function show(Order $order): OrderResource
{
    return new OrderResource($order);
}

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'status' => $this->status,
        'total' => $this->total,
        'currency' => $this->currency,
    ];
}

REST API kontrol listesi

• Açık, çoğul ve öngörülebilir kaynak yolları
• Doğru HTTP yöntemleri ve durum kodları
• Kararlı JSON ve Problem Details hataları
• Belgelenmiş filtreleme, sıralama ve sayfalama
• Kimlik doğrulama, yetki, validation ve rate limit
• Uyumluluk ve sürüm politikası
• OpenAPI, contract test ve gözlemlenebilirlik

Sık sorulan sorular

URL’lerde fiil olmalı mı?

Genellikle hayır. Kaynak isimlerini ve HTTP yöntemlerini kullanın. Gerçek bir iş komutu POST /orders/42/cancellation gibi kaynak olarak modellenebilir.

En önemli kural nedir?

Tutarlılık. Her yerde uygulanan makul bir kural, farklı davranan akıllı uç noktalardan daha kolay tüketilir.