RESTful API Tasarımı ve JSON Akışı

Konu Anlatımı

Uygulama Programlama Arayüzü Neden Gerekir?

Bir uygulama programlama arayüzü, iki yazılımın birbirine veri gönderip alırken uyduğu sözleşmedir. Arayüzün arkasındaki mantık, veri tabanı ve dağıtım biçimi değişse bile sözleşme korunursa istemci tarafında değişiklik gerekmez. Bu ayrım, aynı servisin web sitesi, mobil uygulama ve rapor aracı tarafından kullanılmasını sağlar.

Arayüz tasarımı, kimin neyi sorduğunu netleştirir: hangi veri isteniyor, hangi işlem yapılacak, hangi hata durumunda ne dönecek. Belirsiz bir sözleşme, taraflar arasında sürekli düzeltme gerektirir ve hataları geç fark edilen hâle getirir.

Kaynak Tabanlı Tasarım

Kaynak tabanlı tasarımda her şey bir kaynak olarak düşünülür: öğrenci, ders, sınav kaydı. Kaynak çoğul isimle adlandırılır ve tek bir kayıt kimliğiyle belirtilir. Eylem ayrı bir uç noktada değil, kaynağın hangi durumda olduğuna göre istek yöntemiyle belirlenir. Bu yaklaşımda uç nokta sayısı azalır, arayüz anlaşılır ve tutarlı hâle gelir.

İstemcinin bir kaynağı isteyip istemediğine, kaynağı değiştirip değiştirmediğine ve kaynağı silip silmediğine karar veren yöntemler standarttır. Bir işlem başka bir işlem yaratmıyorsa tekrar gönderildiğinde ikinci kez etki üretmemelidir; buna tekrar etkisizlik denir. Ödeme gibi kritik işlemlerde istemci, sunucunun çift kayıt oluşturmasını önlemek için bir istek anahtarı gönderir.

Sürümleme ve Geriye Uyum

Arayüz sözleşmesi zamanla değişir. Bu değişiklikler kontrollü olmalıdır. Sürümleme, değişikliğin adres yolunda ya da başlıkta açıkça belirtilmesidir. Yeni alan eklemek geriye uyumludur; bir alanın tipini değiştirmek ya da alanı kaldırmak geriye uyumsuzdur ve yeni sürüm gerektirir.

Uyumlu olmayan bir değişiklik yapıldığında eski istemciler çalışmaz hâle gelir. Bu nedenle kullanımdan kaldırılacak alan ve yöntemler önceden ilan edilir, ölçüm verileriyle desteklenir ve istemcilerin geçiş yapması için süre tanınır. Kaldırılan sürümlere ait ağ günlükleri, hangi istemcinin etkilendiğini göstermek için saklanır.

Sayfalama, Sıralama ve Filtreleme

Bir kaynak tümüyle döndürülmemelidir. Sayfalama, veriyi parçalara bölerek hem sunucu hem istemci yükünü sınırlar. İstemci, devam işaretini isteyin sunucu bir sonraki parçayı döner; böylece veri taşınmaz ve bellek kullanılmaz. Sayfa boyutu büyüdükçe istek sayısı azalır, tek istekte taşınan veri artar; bu denge veri boyutuna göre kurulmalıdır.

Sıralama ve filtreleme kuralları da sözleşmede yazılır. İstemcinin istediği sıralama alanını sunucu doğrulamalı bir listeden seçmelidir, aksi hâlde istediği sütun üzerinden pahalı tarama yapılabilir. Filtrelemede kullanılan alanlar da aynı biçimde sınırlanır.

• Bir uç noktanın veri boyutu ölçülür ve gereğinden büyükse sayfalanır.
• Sıralama ve filtreleme alanları izinli listeyle sınırlanır.
• Hız sınırı aşıldığında istek reddedilir ve istemciye bekleme süresi bildirilir.
• Hata yanıtı ortak bir biçimdedir: hata kodu, açıklama, istek izleme numarası.
• Her yanıtta önbellek ve sürüm bilgisi başlık olarak taşınır.

Hız Sınırı, İzleme ve Sözleşme Dokümantasyonu

Hız sınırı, bir istemcinin belirli zaman aralığında yapabileceği istek sayısını sınırlar. Sınır aşıldığında istek reddedilir ve ne kadar beklenmesi gerektiği bildirilir; böylece istemci kendini yavaşlatır. Bu önlem, hatalı bir istemcinin sunucuyu tüketmesini engeller.

Kalıcı bir sözleşme için uç noktalar, istek ve yanıt alanları, hata kodları ve örnekler yazılı olarak tanımlanır. Sürüm notları, değişiklik tarihleri ve kullanımdan kaldırma planı bu tanımın parçasıdır. İstek izleme numarası, kullanıcı bildiriminden sunucu günlüğüne kadar aynı olayı izlemeyi sağlar.

Ölçüm tarafında istek sayısı, hata oranı, ortalama yanıt süresi ve dönen veri boyutu izlenir. Bu değerler eşik aştığında sürüm çıkarma, sınır değiştirme veya altyapı kapasitesi kararları veriye dayalı olarak alınır.

RESTful Sözleşme, JSON Akışı ve Hata Biçimi

Bu bölümde bir RESTful API sözleşmesinin nasıl kurulacağını ve verinin JSON akışı olarak nasıl taşınacağını öğreneceğiz. RESTful tasarımda her şey bir kaynak olarak düşünülür; istek yöntemi, kaynağın hangi durumda olması gerektiğini belirtir. Kaynak adı çoğul kullanılır ve tek bir kayıt kimliğiyle belirtilir.

Veri JSON biçiminde taşınır: çift tırnaklı alan adları ve değerleri, çift tırnaklı sayılar, hatalar için ortak bir gövde yapısı kullanılır. Hata gövdesinde hata kodu, açıklama ve istek izleme numarası bulunur; bu numara kullanıcı bildiriminden sunucu günlüğüne kadar aynı olayı izlemeyi sağlar. Yanıt başlıklarında sürüm ve önbellek bilgisi taşınır.

Günlük Hayattan Bir Örnek

Bir mobil uygulama, sunucudan öğrenci listesini isteyen bir API çağrısı yapıyordu. Sunucu her seferinde listenin tamamını gönderdiği için uygulama yavaş açılıyordu. Sayfalama eklenip veri akışı parçalara bölündüğünde hem ağ hem bellek yükü azaldı; aynı zamanda JSON hata biçimi ortaklaştırıldığı için uygulama tarafındaki hata yönetimi sadeleşti.

Özet

• RESTful tasarımda her şey kaynak olarak düşünülür.
• Kaynak adı çoğul olur ve kimlikle belirtilir.
• Veri JSON biçiminde taşınır.
• Tekrar eden istek ikinci kez etki üretmemelidir.
• Hata gövdesi ortak yapıdadır ve izleme numarası taşır.

Sık Yapılan Hatalar

1. Aksiyon için ayrı uç nokta açmak: Kaynağın durumunu yöntemle belirtmek, uç nokta sayısını azaltır ve sözleşmeyi tutarlı kılar.
2. Hata biçimini değiştirmek: Hata gövdesi ortak değilse istemci her seferinde yeni biçimle uğraşmak zorunda kalır.
3. Sayfalamayı atlamak: Kaynak tümüyle döndürülürse sunucu ve istemci yükü gereksiz biçimde büyür.

Ne Öğreneceğiz

Kaynak tabanlı uç nokta tasarımı, sürümleme, sayfalama, hız sınırı ve hata sözleşmesi kurallarıyla sunucu ve istemci arasındaki veri akışını düzenler. Bu konuda ögrenme çıktıları:

• Kaynak tabanlı tasarımda uç nokta adlandırmasını ve çok biçimli yanıtları doğru kurar.
• Sayfalama, sıralama ve filtreleme kurallarıyla istemcinin veri taşıma yükünü sınırlar.
• Sürümleme ve geriye uyum kurallarıyla istemci güncellemelerini güvenli biçimde yönetir.
• Hız sınırı, yeniden deneme ve tekrar etkisizlik kurallarını hata senaryolarına uygular.
• Hata yanıtlarını ortak bir sözleşmeyle standartlaştırıp izleme bilgisine dönüştürür.

Ön Bilgi

Bu konuya başlamadan önce temel kavram ve ön koşulları kavramanız yardımcı olacaktır. Konunun çerçevesinde şu kavramlar dikkat ister:

• Uç nokta adları çoğul kaynak adı ve tekil kayıt kimliğinden oluşur.
• Sayfalama olmadan tüm veri döndürmek sunucu ve ağ yükünü gereksiz artırır.
• Uyumlu olmayan alan değişiklikleri yeni sürüm gerektirir, sessizce değiştirilmez.
• Hız sınırı aşımında istek reddedilir ve bekleme süresi istemciye bildirilir.
• Kritik işlemlerde istek anahtarı ile çift kayıt oluşması engellenir.
• Hata yanıtı ortak sözleşmeye uyar ve izleme numarası taşır.

İleri Örnek

Daha ileri bir uygulama:

Soru: Bir uç nokta 2000 kaydın tamamını döndürmektedir ve her kayıt 1,5 KB veri içermektedir.

1. Kayıt sayısını yaz.
2. Kayıt başına veri boyutunu yaz.
3. Çarp ve birimi koru.

Sonuç/cevap: 2000 × 1,5 = 3000 KB veri döner. Bu boyut tek yanıtta taşınması riskli olduğundan sayfalama eklenmeli, istemciye yalnızca ihtiyacı olan alanlar sunulmalıdır.

Adım Adım Çözülmüş Örnek

Sayfa sayısını hesaplama konusunun adımları:

1. Toplam kayıt sayısını yaz.
2. Sayfa başına kayıt sayısına böl.
3. Kalan varsa bir sayfa ekle.

Karşılaştırma Tablosu

Kendini Dene

Soru: Yönerge: Bir okulun öğrenci kayıt uygulaması için arayüz tasarlanıyor. (I) uç nokta listesini ve adlandırmalarını, (II) yetkilendirme kurallarını, (III) sayfalama ve filtreleme kurallarını, (IV) hata sözleşmesini madde madde yaz.

Örnek cevap: Puanlama anahtarı: Uç nokta listesi ve adlandırma gerekçesiyle verilmesi 7 puan; yetkilendirme kurallarının yazılması 6 puan; sayfalama ve filtreleme kurallarının belirlenmesi 6 puan; hata sözleşmesinin tanımlanması 6 puan. Toplam 25 puan. Model cevap: Uç noktalar kaynak adıyla kurulur; kayıt listesi ve tekil kayıt uçları, kayıt oluşturma, güncelleme ve silme işlemleri, ayrıca öğrencinin kendi kayıtlarına özel bir uç tanımlanır. Yetkilendirmede öğrenci yalnızca kendi kayıtlarını, öğretmen kendi sınıfını görebilir. Sayfalamada sayfa boyutu ve devam işareti tanımlanır, filtreleme alanları izinli listeyle sınırlanır. Hata sözleşmesinde hata kodu, açıklama ve istek izleme numarası yer alır.