RESTful API tasarımının temelleri

Bir noktada Laravel projelerine mobil uygulama ya da başka bir istemci eklemem gerekti ve doğal olarak API yazmaya başladım. İlk API’lerim şöyle görünüyordu: /kullanici/getir, /kullanici/kaydet, /siparis/listele. Çalışıyordu ama bir süre sonra URL sayısı arttıkça hangisinin ne yaptığını takip etmek güçleşti.

REST (Representational State Transfer), bu karmaşanın önüne geçmek için yerleşik bir yaklaşım sunuyor. Bu yazıda REST’in üç temel yapı taşını — kaynak, HTTP yöntemi ve durum kodu — anlatacağım. Bunları anlamak, bir API’yi tahmin edilebilir kılmanın yeterli ama kolay gözden kaçan temelidir.

Kaynak (Resource) nedir?

REST’te her şey bir **kaynak (resource)**tır. Kaynak, uygulamanızdaki bir varlığı temsil eder: kullanıcı, sipariş, ürün, yorum gibi. Kaynaklar URL ile adreslenir.

Kaynak URL’leri isim tabanlı olur, fiil içermez:

# Yanlış
GET /kullanicilari-getir
POST /yeni-kullanici-olustur

# Doğru
GET /users
POST /users

Çoğul isim kullanmak yaygın kuraldır: /users, /orders, /products.

Bir kaynağın tekil örneğine erişmek için kimliği (ID) URL’ye eklenir:

GET /users/42        → 42 numaralı kullanıcı
GET /orders/7        → 7 numaralı sipariş

İlişkili kaynaklar için iç içe yapı kullanılır:

GET /users/42/orders → 42 numaralı kullanıcının siparişleri

HTTP yöntemleri (Methods)

URL kaynağı tanımlarken, HTTP yöntemi (HTTP Method) o kaynak üzerinde ne yapılacağını söyler. Beş ana yöntem var:

Yöntem	Anlamı	Örnek
GET	Kaynağı oku	GET /users/42
POST	Yeni kaynak oluştur	POST /users
PUT	Kaynağı tamamen güncelle	PUT /users/42
PATCH	Kaynağı kısmen güncelle	PATCH /users/42
DELETE	Kaynağı sil	DELETE /users/42

Bu yöntemleri doğru kullanmak, API’nizi tanıyan biri için neyin ne yapacağını tahmin edilebilir kılar. GET /users/42 çağrıldığında sunucu tarafında bir şeyin değişmeyeceğini bilirsiniz. DELETE /users/42 çağrıldığında ne beklediğiniz açık.

Eski HTML form tabanlı yaklaşımlarda yalnızca GET ve POST kullanırdık. REST API’lerinde tüm yöntemlerden yararlanmak anlamı netleştirir.

Durum kodları (Status Codes)

HTTP durum kodu (HTTP Status Code), sunucunun isteğe nasıl yanıt verdiğini söyler. Birkaç yüz koddan oluşan bir standart; ama pratikte az sayıda kodu bilmek yeterli.

Başarılı yanıtlar (2xx):

• 200 OK — İstek başarılı, veri dönüyor
• 201 Created — Kaynak başarıyla oluşturuldu
• 204 No Content — Başarılı ama döndürülecek içerik yok (genellikle DELETE sonrası)

İstemci hataları (4xx):

• 400 Bad Request — Gönderilen veri hatalı ya da eksik
• 401 Unauthorized — Kimlik doğrulama gerekiyor
• 403 Forbidden — Kimlik doğrulandı ama yetki yok
• 404 Not Found — İstenen kaynak bulunamadı
• 422 Unprocessable Entity — Veri formatı doğru ama içerik doğrulamadan geçemedi

Sunucu hataları (5xx):

• 500 Internal Server Error — Sunucu tarafında beklenmeyen hata

Bunları tutarlı kullanmak önemli. Her hata için 200 OK dönüp yanıt gövdesine "error": true yazmak çalışır ama REST prensibine aykırı; ve HTTP araçlarıyla (Postman, curl, tarayıcı eklentileri) çalışırken kodu yorumlamayı güçleştirir.

Gerçek bir örnek

Bir sipariş kaynağı için basit bir API tasarımı şöyle görünebilir:

GET    /orders         → Tüm siparişleri listele    → 200 OK
POST   /orders         → Yeni sipariş oluştur       → 201 Created
GET    /orders/7       → 7 numaralı siparişi getir  → 200 OK
PUT    /orders/7       → Siparişi güncelle           → 200 OK
DELETE /orders/7       → Siparişi sil               → 204 No Content

Beş URL ve beş yöntemle tüm CRUD işlemleri karşılanıyor. Bu yapıyı bilen biri kodu görmeden API’nin ne yapabileceğini tahmin edebilir.

Neden bu kadar önemli?

REST kurallarını takip etmenin zorunluluğu yok — PHP sizi durdurmaz. Ama bir API istemcisi (mobil uygulama, başka bir servis, frontend) yazan kişi için tahmin edilebilirlik büyük kolaylık sağlar. Ayrıca Postman, Swagger gibi araçlar REST kurallarına uygun API’lerle çok daha iyi çalışır.

Bunları öğrendikten sonra eski /kullanici/getir URL’lerime baktım ve tek tek düzelttim. Biraz zaman aldı ama API’yi kullanan taraftaki kafa karışıklığı gitti.