REST API Tasarımı: Küçük Ekipte Sade Sözleşme

Tek POST ucuna her işi yığmak ilk hafta hızlı görünür; birkaç istemci sonra sözleşme okunmaz hale gelir. Bu rehber, REST API tasarımını kaynak, HTTP fiili ve hata gövdesiyle sadeleştirmeniz için uygulanabilir bir çerçeve sunar. Küçük ekip tek sayfalık sözleşmeyle uçları ve hataları tahmin işi olmaktan çıkarır.

Küçük ekiplerde backend çoğu zaman tek bir POST ucuyla açılır. Gövdeye bir action alanı konur, her yeni ihtiyaç aynı adrese eklenir; ilk teslim hızlı görünür. Birkaç istemci ve birkaç hafta sonra kimse hangi alanın neyi değiştirdiğini güvenle söyleyemez. REST API tasarımı tam bu noktada tempo düşürmek için değil; kaynağı, fiili ve hata gövdesini okunabilir bir sözleşmeye bağlamak için işe yarar.

Bu rehber, her işi tek uca yığmak yerine küçük ekibin günlük temposuna yetecek sade bir çerçeve sunar. Amaç kalın bir standart kitabı yazmak değildir. Bir sonraki geliştiricinin, siz dahil, uçları belgelemeden tahmin etmek zorunda kalmamasıdır.

Her İşi Tek POST Ucuna Yığmak Neden Bozulur

Tek uç modeli caziptir: yeni iş için yeni rota düşünmezsiniz. olustur, iptal, stok_dus gibi değerler aynı gövdeye eklenir. Asıl kırılma, fiilin gizlenmesi ve hata anlamının kaybolmasıdır. Aynı adres hem kayıt açar hem silerse istemci hangi durumda ne bekleyeceğini bilemez.

Yetki de dağılır. İptal hakkı olmayan bir oturum, oluşturma gövdesine iptal alanı ekleyerek iş kuralını dolanabilir. Günlüklerde her satır aynı yolu gösterir; hangi işin kırıldığını ayıklamak zorlaşır. Alan adları şişer, kimse kullanılmayan parametreyi silmeye cesaret edemez.

• Fiil URL’de ve HTTP yönteminde görünmez; gövdenin içine gömülür.
• İş kuralı hataları çoğu zaman 200 gövdesinde ok: false ile döner.
• Mobil, admin ve entegrasyon aynı belirsiz sözleşmeyi kopyalar.
• İstemci testleri “bu action bugün ne anlama geliyor” sorusuna bağlanır.

Okunur sözleşme şu üç soruyu bakınca yanıtlar: ne üzerinde çalışıyorum, hangi fiili uyguluyorum, başarısız olursa gövde bana ne söylüyor?

REST API Tasarımı: Kaynağı ve Fiili Ayırın

REST API tasarımı, her işlemi bir kaynak ve o kaynağa uygulanan bir fiil olarak okumanızı ister. Kaynak veritabanı tablosu olmak zorunda değildir; iş dilindeki nesnedir: sipariş, müşteri, sepet kalemi, kargo kaydı. Kimlik o nesnenin kararlı yoludur. /siparisler/1847 ifadesi “bu sipariş” demenin sözleşmesidir.

Fiili HTTP yöntemine bağlayın. Listelemek ve tek kayıt okumak yan etkisiz kalır. Oluşturmak, kısmi güncellemek ve silmek ayrı fiillerdir. “Siparişi onayla” çoğu üründe yeni bir kaynak değil, siparişin durum alanına kontrollü bir geçiştir. Onayı ayrı alt kaynak yapmak, yalnızca onayın kendi belgesi, geçmişi veya iptal akışı varsa anlamlıdır.

Kaynak sayısını şişirmeyin. Her düğme için yeni koleksiyon açmak, tek POST yığmak kadar okunaksızdır. Dış isim iş dilinde kalsın. Tablo adı siparis_kalemleri_v2 olsa bile dış yolda /siparisler/{id}/kalemler yeterlidir. İç şema değişebilir; sözleşme değişmek zorunda değildir.

KepezWeb olarak küçük ekiplere önce nesneyi adlandırmalarını, sonra fiili yöntemle eşleştirmelerini öneririz. Kod, bu listenin uygulamasıdır; listenin kendisi değildir.

Okunur URL ve HTTP Yöntemini Birlikte Seçin

Yol çoğul kaynak, kimlik ve gerekiyorsa alt kaynaktan oluşur. Fiili yola yazmayın. /siparisler/1847/iptalEt gibi bir adres, yöntemi URL’ye gizler ve sözleşmeyi tekrar action listesine çevirir. İptal, sipariş üzerinde bir durum değişimi veya ayrı bir iptal kaydıysa bunu yöntem ve gövdeyle gösterin.

Yaklaşım	Ne zaman idare eder	Nerede kırılır
Tek POST + action	Tek istemci, kısa ömürlü deneme	Yetki, log ve hata anlamı karışınca
Kaynak + HTTP fiili	Birden fazla istemci, uzun ömür	Her düğmeye ayrı koleksiyon açınca
GET /siparisler	Liste; yan etki yok	Gövdeyle filtre veya gizli yazma
POST /siparisler	Yeni kaynak oluşturma	Her işi aynı POST’a yüklemek
PATCH /siparisler/{id}	Kısmi güncelleme, durum geçişi	Eksik gövdeyi tam replace sanmak

PUT ile PATCH’i ekip içinde tek kurala bağlayın. PUT gövdenin tamamını temsil eder; eksik alan silinmiş sayılabilir. PATCH yalnızca gönderilen alanları değiştirir. Küçük ekipte çoğu güncelleme PATCH ile daha az sürpriz üretir. GET’e gövde koymayın. Filtre ve sıralama sorgu dizesinde kalsın.

Koleksiyon POST’u oluşturma içindir. “Her şeyi POST’la” alışkanlığı, önbelleği ve tekrar denemeyi bozar. Aynı oluşturma isteğinin ikinci kez gelmesi yeni kayıt mı üretecek, yoksa aynı kaydı mı döndürecek? Bunu sözleşmede yazın. Ödeme gibi yan etkili işlerde istemcinin gönderdiği bir tekrar anahtarı, çift kaydı kesmenin sade yoludur.

Hata Gövdesini Sözleşmenin Parçası Yapın

Yalnızca HTTP durum kodu yetmez. 400, 404 ve 409 istemciye kapı gösterir; kapının arkasındaki iş kuralını göstermez. “Stok yok” ile “beden alanı eksik” aynı 400 içinde kaybolursa arayüz doğru mesajı bağlayamaz. Hata gövdesini de kaynak ve fiil kadar sabit tutun.

Küçük ekip için üç alan çoğu üründe yeter:

• kod: makinenin ayırdığı kararlı kimlik, örneğin STOK_YETERSIZ.
• mesaj: insana okunan, suçlamayan kısa metin.
• hedef: varsa hangi alan veya kaynak parçası.

409 Conflict. kod: STOK_YETERSIZ. mesaj: Bu beden için stok kalmadı. hedef: beden

Durum kodunu iş kuralına göre seçin. Doğrulama 400, bulunamayan kayıt 404, yetki 401 veya 403, çakışan durum 409, beklenmeyen sunucu hatası 500 ailesi. 200 dönüp gövbede success: false bırakmak, izlemeyi ve istemci dallanmasını körleştirir. Mesajı çeviriye açacaksanız kodu sabitleyin; metin değişebilir, kod değişmesin.

Aynı hata şeklini tüm uçlarda kullanın. Sipariş bir biçimde, üye başka biçimde dönerse mobil ekip her ekranda ayrı ayrıştırıcı yazar. Tek şekil, tek yardımcı fonksiyon demektir.

Küçük Ekip İçin Tek Sayfalık Sözleşme

Belgeyi şişirmeyin. Bir sayfa, depoda duran ve gözden geçirmeden değişmeyen bir metin yeter. KepezWeb olarak bu sayfayı koddan önce kilitlemenizi öneririz; uç listesi netleşmeden iş kuralı gövdeye dağılır.

Sayfada şunlar dursun:

1. Temel adres ve ortam ayrımı (geliştirme / canlı).
2. Kimlik başlığı: hangi başlık, hangi şema, süresi dolunca hangi hata kodu.
3. Kaynak tablosu: yol, yöntem, tek cümlelik anlam, yan etki var mı.
4. Başarı gövdesinin iskeleti: kimlik, zaman, asıl veri.
5. Hata gövdesinin iskeleti: kod, mesaj, hedef.
6. Listeleme: sayfa, boyut, sıralama alanları.
7. Tarih ve para formatı: ekip içinde tek seçim.
8. Tekrar deneme kuralı: hangi POST’lar tekrar anahtarı ister.

Bu liste, yazılım geliştirme işinde ekranlardan önce konuşulacak ortak dildir. Tasarımcı “iptal butonu”, geliştirici “PATCH /siparisler/{id} ve durum=iptal” der. Aynı cümleyi paylaşınca entegre günü kısalır.

Sözleşmeyi yorum satırına gizlemeyin. İstemci ekibi yalnızca canlı deneme ile öğrenirse, sizin “geçici” dediğiniz alan kalıcı bağımlılık olur. Bir örnek istek ve bir örnek hata, uzun anlatıdan daha çok iş görür.

Yan Etki, Bekleyen İş ve Bildirim

REST yanıtı hemen biten işler içindir. Ödeme onayı, kargo etiketi, uzun rapor gibi işler isteği dakikalarca açık tutmamalıdır. Bu durumda kaynağı “kabul edildi, işleniyor” durumuna alın; sonucu sonra yazın. İstemci GET ile durumu sorar veya siz dışarıya haber verirsiniz.

Haber verme tarafı REST ucunun yerine geçmez; onu tamamlar. Ödeme veya kargo gibi olaylarda webhook ile bildirim sözleşmeye ayrı bir bölüm olarak eklenir: hangi olay, hangi gövde, başarısız teslimde nasıl tekrar deneneceği. Böylece API “şimdi bitir” baskısından kurtulur.

Kimliği de sade tutun. Her uca farklı anahtar şeması koymayın. Süre dolunca aynı hata gövdesini dönün. Yönetici ve müşteri uçlarını yetkiyle ayırın, gizli bir action parametresiyle değil.

Yayına Çıkmadan Önce Kısa Kontrol Listesi

Uçlar çalışıyor diye sözleşme bitmiş sayılmaz. Aşağıdaki liste, küçük ekibin gözden geçirme kapısı olabilir:

• Her iş kuralı bir kaynak ve bir yöntemle eşleşiyor mu?
• Fiil hâlâ gövdede action olarak duruyor mu?
• Hata gövdesi tüm uçlarda aynı üç alanı taşıyor mu?
• GET yan etkisiz mi; tekrarlanan POST çift kayıt üretiyor mu?
• Kimlik alanı örneklerde gerçekçi mi, “test123” gizli kalmış mı?
• İstemcinin ihtiyaç duymadığı alanlar yanıtta şişiyor mu?

Bu kapıyı insan belleğine bırakmayın. Sözleşme örneklerini otomatik teste bağlamak, birleştirmeyi güvenli kılar. Küçük ekipte bunu şişirmeden kurmak için CI/CD pipeline hattına sözleşme testini eklemek yeter; kurumsal bir araç ormanı gerekmez.

Sıkça Sorulan Sorular

REST API tasarımı küçük ekip için fazla resmi değil mi?

Değil. Resmi olan kalın standart metnidir. Sizin ihtiyacınız kaynak listesi, yöntem ve hata şeklidir. Tek sayfa, tek POST yığınından daha az toplantı üretir.

Her kaynak için beş HTTP yöntemi şart mı?

Hayır. Kullanmadığınız yöntemi açmayın. Yalnızca oluşturulan bir kayıt silinmiyorsa DELETE tanımlamayın. Sözleşme gerçek fiilleri gösterir, simetri tablosunu değil.

Hata için yalnızca durum kodu bırakmak neden yetmez?

Durum kodu sınıfı söyler, iş kuralını söylemez. Aynı 409 hem stok yok hem sipariş zaten iptal anlamında gelebilir. Kararlı bir kod alanı arayüzü ve izlemeyi ayırır.

Eski tek POST ucunu nasıl taşırım?

Yeni kaynak uçlarını yanına ekleyin. Eski action değerlerini bir süre yönlendirin; yeni istemcileri yeni yola alın. Kesme tarihini sözleşmede yazın, sessizce kapatmayın.

Sözleşme belgesi nerede durmalı?

Kodla aynı depoda, kısa ve sürümlenen bir metin olarak. Ayrı bir notta kaybolan sayfa, canlı uçtan kopar. Gözden geçirme, metin değişince yapılır.

Sipariş, üye veya panel tarafında okunur bir API sözleşmesi kurmak istiyorsanız KepezWeb ile kapsamı birlikte sadeleştirebilirsiniz. İhtiyacınızı kısaca yazın; teklif alın ve kaynak listesinden fiile uzanan net bir uç planı üzerinden ilerleyelim.