--- title: "REST API Tasarımı: İyi Bir API Nasıl Kurgulanır?" url: "https://cilginyazilim.com/blog/rest-api-tasarimi-iyi-bir-api-nasil-olur" description: "REST API tasarımında kaynak adlandırma, durum kodları, kimlik doğrulama, sürümleme ve hata biçimi kararları uzun vadede belirleyicidir. Uygulamalı bir rehber." published: "2026-07-11T00:16:29+03:00" modified: "2026-07-31T06:13:20+03:00" author: "superadmin" category: "Kurumsal Yazılım ve Entegrasyon" tags: ["api", "rest", "json", "jwt", "entegrasyon"] site: "CılgınYazılım" language: "tr" --- # REST API Tasarımı: İyi Bir API Nasıl Kurgulanır? Bir API’nin kalitesi kod satırında değil, sözleşmesinde belli olur. Kaynak adlandırma, durum kodları, sürümleme, kimlik doğrulama ve hata biçimi için pratik kurallar. REST API tasarımı, kod yazmadan önce verilen kararların toplamıdır. Bir API yayına çıktıktan sonra onu kullanan istemciler oluşur ve sözleşmeyi değiştirmek pahalı hâle gelir. Bu yüzden iyi API, "çalışan" API değil, *tahmin edilebilir* API’dir: kullanan geliştirici bir uç noktayı gördükten sonra diğerlerini tahmin edebiliyorsa tasarım başarılıdır. ![İyi bir REST API tasarımının beş temel unsuru](http://localhost/ci4/uploads/blog/2026/07/rest-api-tasarimi-iyi-bir-api-nasil-olur-ozet.png) *Bu beş başlık netse, API’yi kullanan ekip belge okumadan tahmin edebilir.* ## 1. Kaynak adlandırma: isimler, fiiller değil Adres satırında yapılan işi değil, üzerinde çalışılan kaynağı belirtin. İşi HTTP metodu anlatır. - `GET /api/v1/orders` — liste - `GET /api/v1/orders/42` — tek kayıt - `POST /api/v1/orders` — oluşturma - `PUT /api/v1/orders/42` — tam güncelleme, `PATCH` — kısmi güncelleme - `DELETE /api/v1/orders/42` — silme `/getOrders`, `/orderDelete` gibi adlandırmalar tutarsızlığın kapısını açar; ekipteki her geliştirici kendi fiilini uydurur. Çoğul isim kullanın ve istisnasız uygulayın. ## 2. Durum kodları: anlamına uygun kullanın Her yanıtı 200 ile dönüp gövdede `success: false` yazmak, istemci tarafında hata yönetimini imkânsız hâle getirir. Asgari sözlük şudur: - **200** başarılı, **201** oluşturuldu, **204** içerik yok (silme sonrası) - **400** istek hatalı, **401** kimlik doğrulanmadı, **403** yetki yok, **404** kaynak yok - **409** çakışma (aynı kayıt zaten var), **422** doğrulama hatası - **429** hız sınırı aşıldı, **500** sunucu hatası 401 ile 403 farkı özellikle önemlidir: birincisi "kim olduğunu bilmiyorum", ikincisi "kim olduğunu biliyorum ama bu işlemi yapamazsın" demektir. ## 3. Hata biçimi tek olmalı Tüm hataların aynı gövde yapısında dönmesi, istemci kodunu sadeleştirir. Örnek bir sözleşme: ``` { "success": false, "error": { "code": "VALIDATION_FAILED", "message": "Gönderilen veri doğrulanamadı.", "fields": { "email": "Geçerli bir e-posta giriniz." } } } ``` Makine tarafından okunacak bir `code`, insana gösterilecek bir `message` ve alan bazlı ayrıntılar. Bu üçlü, arayüzün hatayı doğru yerde göstermesini sağlar. ## 4. Kimlik doğrulama ve yetki Kimlik doğrulama "sen kimsin", yetkilendirme "bunu yapabilir misin" sorusudur. İkincisi çok daha sık atlanır. Kritik kural: **kaydın kime ait olduğu her istekte sunucuda kontrol edilmelidir.** Aksi hâlde kullanıcı adres satırındaki numarayı değiştirerek başkasının verisini okur; bu, IDOR olarak bilinen ve sahada en sık rastlanan açıktır. Token’ların ömrü kısa tutulmalı, yenileme akışı ayrı bir uç noktayla yönetilmeli ve çıkışta jeton geçersiz kılınabilmelidir. Ayrıntılı kontrol listesi için [OWASP REST güvenlik notları](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html) iyi bir başlangıçtır. ## 5. Filtreleme, sıralama, sayfalama Liste uç noktaları büyümeye mahkûmdur. Baştan sınır koyun: varsayılan sayfa boyutu (örneğin 20), en yüksek sayfa boyutu (örneğin 100) ve sorgu parametreleriyle filtreleme. ``` GET /api/v1/orders?status=paid&created_from=2026-01-01&sort=-created_at&page=2&per_page=50 ``` Yanıtın içine toplam kayıt sayısını ve sayfa bilgisini koyun; istemcinin kaç sayfa olduğunu tahmin etmesi gerekmesin. ## 6. Sürümleme ve geriye dönük uyum Yayına çıkmış bir alanı silmek veya adını değiştirmek kırıcı değişikliktir. Yeni alan eklemek ise güvenlidir. Kırıcı değişiklik gerektiğinde yeni sürüm açın ve eskisi için kapanış tarihi duyurun. Mobil uygulamalarda kullanıcıların bir kısmı aylarca eski sürümde kalacağı için bu disiplin zorunludur. ## 7. Belgelendirme ve örnekler API’yi kullanacak kişi, dokümana iki soruyla gelir: bu uç nokta ne döndürür ve hata durumunda ne olur? Her uç nokta için gerçek bir istek ve gerçek bir yanıt örneği koymak, sayfalarca açıklamadan daha etkilidir. Belgeyi koddan üretmek en sürdürülebilir yoldur; elle yazılan dokümanlar üçüncü sürümde gerçeklikten kopar. Ayrıca test ortamı için örnek kimlik bilgileri sağlayın: entegrasyonu yapan geliştiricinin ilk beş dakikada başarılı bir istek atabilmesi, projenin genel süresini belirgin biçimde kısaltır. ## 8. Zaman aşımı, yeniden deneme ve idempotency Ağ üzerinden yapılan her çağrı başarısız olabilir. İstemci isteği gönderip yanıt alamadığında ne yapacağını bilmelidir. Sorun şudur: istek sunucuya ulaşmış ama yanıt kaybolmuşsa, yeniden deneme aynı siparişi iki kez oluşturur. Çözüm, oluşturma isteklerinde tekrar güvenli (idempotent) davranıştır. İstemci her isteğe benzersiz bir anahtar ekler; sunucu aynı anahtarla gelen ikinci isteği yeni kayıt olarak değil, ilk sonucun tekrarı olarak döner. Ödeme, sipariş ve stok hareketi gibi kritik uçlarda bu yaklaşım, çift kayıt sorunlarının tamamını ortadan kaldırır. ## 9. Hız sınırı ve kötüye kullanım koruması Açık bir API, er ya da geç yanlış yazılmış bir istemci tarafından saniyede yüzlerce istekle dövülür. İstemci başına dakikalık sınır koyun, sınır aşıldığında 429 dönün ve `Retry-After` başlığıyla ne kadar bekleneceğini söyleyin. ## Sonuç İyi bir API tasarımı, kullanan geliştiricinin dokümana bakma ihtiyacını azaltır. Tutarlı adlandırma, doğru durum kodları, tek biçim hata gövdesi, her istekte yetki kontrolü ve baştan planlanmış sürümleme; bu beş karar, API’nizin üç yıl sonra hâlâ genişletilebilir olup olmayacağını belirler. ## Sıkça Sorulan Sorular ### REST API’de sürümleme nasıl yapılmalı? En yaygın ve en az sorun çıkaran yöntem adres üzerinden sürümlemedir: /api/v1/orders. Kırıcı bir değişiklik gerektiğinde v2 açılır, v1 belirli bir süre daha desteklenir ve kapanış tarihi önceden duyurulur. ### JWT mi API anahtarı mı kullanmalıyım? Kullanıcı adına işlem yapılan mobil ve web istemcilerde JWT uygundur çünkü kullanıcıya ve rolüne bağlıdır. Sunucudan sunucuya entegrasyonlarda API anahtarı daha basit ve yönetilebilirdir; ikisi bir arada da kullanılabilir. ### Sayfalama nasıl yapılmalı? Küçük ve orta veri kümelerinde sayfa numarası yeterlidir. Veri sürekli değişiyorsa imleç (cursor) tabanlı sayfalama tercih edilmelidir; aksi hâlde araya yeni kayıt girdiğinde kullanıcı aynı satırı iki kez görür. ### API dokümantasyonu için ne kullanmalıyım? OpenAPI (Swagger) tanımı üretmek en yaygın yoldur. Otomatik üretilen dokümana ek olarak her uç nokta için gerçek bir istek-yanıt örneği koyun; entegrasyon yapan kişinin ilk baktığı şey örnektir. --- Kaynak: [REST API Tasarımı: İyi Bir API Nasıl Kurgulanır?](https://cilginyazilim.com/blog/rest-api-tasarimi-iyi-bir-api-nasil-olur)