RESTful API tasarımının temelleri
Kaynak, HTTP yöntemi ve durum kodu üçgeninde bir API'yi tahmin edilebilir kılmanın pratik kuralları, yöntem ve durum kodlarıyla gerçek bir örnek üzerinde.
Kısaca
REST, bir API'yi üç yapı taşıyla tahmin edilebilir kılar: URL'de çoğul isimlerle adlandırılan kaynaklar, onlarla ne yapılacağını söyleyen HTTP yöntemleri ve sonucu bildiren durum kodları. Tutarlı uygulandığında her uç, kodu okumadan tahmin edilebilir.
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. Bu uçları teknik olarak nasıl yazdığımı Laravel ile JSON API uçları yazmak yazısında anlatmıştım; buradaki konu o kodun altındaki tasarım kararları. Ç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; stili Roy Fielding doktora tezi Architectural Styles and the Design of Network-based Software Architectures, 2000 ile ortaya koydu. 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
REST’te hangi HTTP yöntemleri (Methods) kullanılır?
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: RFC 9110: HTTP Semantics, June 2022, “defined semantics are essentially read-only” olan yöntemlere “safe” der ve GET bunlardan biridir. 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.
Pratikte hangi durum kodları (Status Codes) gerekir?
HTTP durum kodu (HTTP Status Code), sunucunun isteğe nasıl yanıt verdiğini söyler. IANA kayıt defterinde birkaç düzine kod listeleniyor; ama pratikte az sayıda kodu bilmek yeterli.
Başarılı yanıtlar (2xx):
200 OK— İstek başarılı, veri dönüyor201 Created— Kaynak başarıyla oluşturuldu (RFC 9110: “the request has been fulfilled and has resulted in one or more new resources being created”)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 eksik401 Unauthorized— Kimlik doğrulama gerekiyor403 Forbidden— Kimlik doğrulandı ama yetki yok404 Not Found— İstenen kaynak bulunamadı422 Unprocessable Entity(RFC 9110’da adı Unprocessable Content olarak değişti) — 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.
Sık sorulanlar
5 soru
-
REST'te kaynak (resource) nedir?
REST'te her şey bir kaynaktır: kullanıcı, sipariş, ürün, yorum gibi uygulamanızdaki bir varlık. Kaynaklar URL ile adreslenir; bu URL'ler isim tabanlı olur ve fiil içermez. Çoğul isim kullanmak yaygın kuraldır: /users, /orders, /products.
-
REST'te hangi HTTP yöntemleri kullanılır?
Beş ana yöntem var. GET kaynağı okur, POST yeni kaynak oluşturur, PUT kaynağı tamamen günceller, PATCH kısmen günceller, DELETE siler. URL kaynağı tanımlar, yöntem ise sunucuya o kaynakla ne yapacağını söyler.
-
Pratikte hangi durum kodları gerekir?
Pratikte az sayıda kodu bilmek yeterli: başarı için 200 OK, 201 Created ve 204 No Content; istemci hataları için 400, 401, 403, 404 ve 422; sunucuda beklenmeyen hata için 500.
-
Her yanıtta 200 OK dönüp hatayı gövdeye yazmak neden sorun?
Çalışır ama REST prensibine aykırıdır. Üstelik Postman, curl ve tarayıcı eklentileri gibi HTTP araçlarıyla çalışırken ne olduğunu anlamak için yanıt gövdesini yorumlamanız gerekir, bu da işi güçleştirir.
-
REST kurallarına uymak neden önemli?
Uyma zorunluluğu yok, PHP sizi durdurmaz. Ama bir API istemcisi yazan kişi için tahmin edilebilirlik büyük kolaylıktır. Postman ve Swagger gibi araçlar da REST kurallarına uygun API'lerle çok daha iyi çalışır. Tutarlı bir tasarımda deseni bilen biri kodu görmeden API'nin ne yapabileceğini tahmin edebilir.
Bu konudaki deneyler
Kaydırmalı bilgi yarışmasında skoru istemci hesaplıyor, sunucu server_nonce ve HMAC imzasıyla doğruluyor. Bu güven sorununun yapım notları.
Şu an ne yapıyor
Kaydırmalı doğru/yanlış bilgi yarışması bir mobil uygulama olarak çekirdek döngüsüyle uçtan uca çalışıyor; skoru istemci üretse de server_nonce ve HMAC imzasıyla sunucu tarafında doğrulanıyor. swipenor.com uygulamanın tanıtım sayfasıdır, oyunun kendisi değil.
Yorumlar
Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.