REST API Tasarımının Altın Kuralları: Kaynaklar, Metotlar ve Durum Kodları

Bir yazılım sistemi ne kadar iyi çalışırsa çalışsın, dış dünyaya açtığı kapı olan API'si dağınıksa, onu kullanmak zorunda kalan herkes acı çeker. REST (Representational State Transfer), tam da bu kapıyı düzenli, tahmin edilebilir ve tutarlı hale getirmek için ortaya çıkmış bir mimari yaklaşımdır. İyi tasarlanmış bir REST API, dokümantasyonu okunmadan bile büyük ölçüde anlaşılabilir; çünkü belirli kurallara sadıktır. Bu yazıda, yıllardır entegrasyon projelerinde işe yaradığını gördüğümüz altın kuralları, gerçek örneklerle ele alacağız.

Her Şeyden Önce: Kaynak Düşüncesi

REST'in kalbinde "kaynak" (resource) kavramı yatar. Kaynak, sisteminizde anlam taşıyan bir varlıktır: bir sipariş, bir müşteri, bir ürün, bir fatura. API tasarımının ilk adımı, fiilleri değil kaynakları düşünmektir. Yaygın bir hata, uç noktaları eylem odaklı isimlendirmektir: /siparisOlustur, /musteriGetir gibi. Bu yaklaşım hızla kontrolden çıkar; çünkü her yeni ihtiyaç yeni bir fiil doğurur.

REST felsefesinde eylemi HTTP metodu belirtir, kaynağı ise URL. Yani /orders bir kaynak koleksiyonudur; onu oluşturmak, okumak veya silmek metodun görevidir. Bu ayrım basit görünür ama tüm tasarımın temelini oluşturur.

• Koleksiyon: /orders — tüm siparişler.
• Tekil kaynak: /orders/1024 — belirli bir sipariş.
• Alt kaynak: /orders/1024/items — o siparişe ait kalemler.

URL İsimlendirmede Tutarlılık

Bir API'yi kullanılabilir kılan en önemli şey öngörülebilirliktir. Eğer bir uç nokta /orders, diğeri /Customer, bir başkası /product_list ise geliştirici her seferinde tahmin etmek zorunda kalır. Tutarlılık için şu ilkelere sadık kalın:

1. Kaynak adlarını çoğul ve küçük harfle yazın: /products, /invoices.
2. Birden çok kelime için tire kullanın: /order-items, alt çizgi veya deve notasyonu değil.
3. URL'de fiil bulundurmayın; eylem HTTP metodunun işidir.
4. Hiyerarşiyi URL'de yansıtın: /customers/42/orders.

İyi bir API, dokümantasyonu okunmadan bir sonraki uç noktanın nasıl adlandırılacağını tahmin ettirebiliyorsa doğru yoldadır. Sürprizler, entegrasyonun düşmanıdır.

HTTP Metotlarını Doğru Kullanmak

Her HTTP metodunun bir anlamı ve beklenen bir davranışı vardır. Bu anlamlara sadık kalmak, hem sizin hem de API'nizi kullananların hayatını kolaylaştırır.

• GET: Veri okur, hiçbir şeyi değiştirmez. Güvenli ve tekrarlanabilir (idempotent) olmalıdır.
• POST: Yeni bir kaynak oluşturur. Aynı isteği iki kez göndermek iki kayıt yaratabilir.
• PUT: Var olan bir kaynağı tümüyle günceller; idempotenttir.
• PATCH: Kaynağın yalnızca belirtilen alanlarını günceller.
• DELETE: Kaynağı siler; idempotent olmalıdır.

GET isteğinin bir veriyi değiştirmesi ya da DELETE'in yan etki üretmesi, entegrasyonlarda en zor yakalanan hataların kaynağıdır. Örneğin bir arama motoru botunun GET ile sayfayı gezdiği sırada kayıt silmesi ciddi veri kaybına yol açabilir.

Kısa Bir PHP Örneği

Basit bir yönlendirme mantığı, metoda göre kaynak üzerinde ne yapılacağını belirler:

$method = $_SERVER['REQUEST_METHOD'];

switch ($method) {
    case 'GET':
        $order = $repo->find($id);
        http_response_code($order ? 200 : 404);
        echo json_encode($order);
        break;
    case 'DELETE':
        $repo->delete($id);
        http_response_code(204);
        break;
}

Durum Kodları: API'nizin Vücut Dili

HTTP durum kodları, isteğin sonucunu tek bakışta anlatır. Her şeye 200 dönmek yaygın ama zararlı bir alışkanlıktır; çünkü istemci, gövdeyi ayrıştırmadan başarıyı anlayamaz. Doğru kod, iyi tasarlanmış bir API'nin işaretidir.

• 2xx — Başarı: 200 (tamam), 201 (oluşturuldu), 204 (içerik yok).
• 4xx — İstemci hatası: 400 (geçersiz istek), 401 (kimlik doğrulanmadı), 403 (yetki yok), 404 (bulunamadı), 409 (çakışma), 422 (doğrulama hatası).
• 5xx — Sunucu hatası: 500 (beklenmeyen hata), 503 (hizmet dışı).

401 ile 403 arasındaki farkı karıştırmamak önemlidir: 401 "kim olduğunu bilmiyorum", 403 ise "kim olduğunu biliyorum ama buna iznin yok" demektir. Bu ayrım, güvenlik akışlarını doğru kurmanın anahtarıdır.

Hata Yanıtları ve Sayfalama

Hata durumunda tutarlı bir gövde döndürmek, API'nizi kullananların işini büyük ölçüde kolaylaştırır. Her hata için makine tarafından okunabilir bir kod, insan tarafından okunabilir bir mesaj ve mümkünse hangi alanın sorunlu olduğunu belirtin. Ayrıca büyük koleksiyonları asla tek seferde döndürmeyin; sayfalama (pagination) parametreleri sunun: ?page=2&limit=50. Sayfalama olmadan bir /orders uç noktası, veri büyüdükçe hem sunucuyu hem istemciyi boğar.

Bir API'nin kalitesi, işler yolunda gittiğinde değil, işler ters gittiğinde ne kadar açık konuştuğuyla ölçülür.

Sürüm ve Belgelendirme

API'niz büyüdükçe değişecektir; bu kaçınılmazdır. Değişikliklerin mevcut kullanıcıları kırmaması için sürümleme baştan planlanmalıdır. En yaygın yaklaşım, URL'de sürüm belirtmektir: /v1/orders. Ayrıca OpenAPI (Swagger) gibi bir standartla belgelendirme yapmak, hem geliştiricilerin işini hızlandırır hem de test araçlarıyla entegrasyonu kolaylaştırır.

Berasoft olarak özel yazılım projelerinde, dışarıya açılan her API'yi bu ilkelere göre kurgulamaya özen gösteriyoruz; çünkü bugün temiz tasarlanan bir arayüz, yarınki entegrasyon maliyetini belirgin biçimde düşürür. Kurumsal bir sistemi dış servislerle konuşacak hale getirmek istiyorsanız projenizi konuşalım.

Sonuç

REST API tasarımı, karmaşık bir sanat değil; disiplinli bir alışkanlıklar bütünüdür. Kaynak odaklı düşünmek, HTTP metotlarına ve durum kodlarına sadık kalmak, tutarlı isimlendirme ve açık hata yanıtları sunmak — bu birkaç ilke, API'nizi kullananların size teşekkür etmesini sağlar. Unutmayın: bir API'yi çoğu zaman siz değil, başkaları kullanır. Onun için tasarımı sadelik, öngörülebilirlik ve tutarlılık üzerine kurmak, uzun vadede en büyük yatırımdır.