Son zamanlarda, API'leri "sadece POST" kullanarak tasarlamayı mı tartışmalısınız? Dikkatimi çekti. Bu tartışmanın derinliklerine daldıktan sonra, insanların tartıştığı konunun sadece anlamsız olmadığını, aynı zamanda birçok geliştiricinin API tasarımının özünü yanlış anladığını ortaya koyduğunu buldum. Bugün, API tasarımının temel fikirlerine daha derinlemesine dalalım ve bu tartışmanın neden en başta var olmaması gerektiğini görelim.
"Sadece POST" Yanılgısı#
"Sadece POST" kullanarak RESTful API spesifikasyonlarını değiştirmeyi savunan o geliştiriciler, açıkça API tasarımının en önemli noktasını kavrayamamışlar. İddiaları genellikle şunları içerir:
- Tasarımı basitleştirme: Bir yöntem her şeyi halledebilir
- Güvenlik: POST parametreleri URL’de görünmez
- Esneklik: POST her türlü veri yapısını gönderebilir
İlk bakışta, bu iddialar mantıklı gibi görünebilir. Ancak gerçekte, bu görüş, HTTP yöntemlerinin seçimleri ile API tasarım stillerini, iki farklı seviyedeki konuları karıştırıyor. POST, HTTP protokolünün sadece bir yöntemidir, oysa REST bir API tasarım tarzıdır.
API Tasarımının Esası#
Belirli API stillerini tartışmadan önce, API tasarımının temel amacının ne olduğunu anlamalıyız. İyi bir API olmalıdır:
- Açık ve anlaşılır: Diğer geliştiriciler (gelebilecek olan gelecekteki siz dahil) her bir uç noktanın amacını sezgisel olarak anlayabilmelidir
- Tutarlı: Öğrenme maliyetlerini azaltmak için belirli spesifikasyonlara uyun
- Genişletilebilir: Kolayca sürüm kontrolü ve işlevsel genişleme yapabilir
- Verimli: Performans ve kaynak kullanımı açısından verimliliği düşünün
RESTful API: Sadece HTTP Yöntemlerinin Seçiminden Daha Fazlası#
RESTful API, birçok API tasarım stilinden sadece biridir ve kaynaklar ve kaynak üzerindeki işlemlere odaklanır. RESTful API’nin nasıl tasarlandığını görmek için basit bir blog sistemi örneğini ele alalım:
-
Tüm makaleleri al:
-
Belirli bir makaleyi al:
-
Yeni bir makale oluştur:
-
Bir makaleyi güncelle:
-
Bir makaleyi sil:
Bu örnekte, şunları görebiliriz:
- API, "makale" kaynağı etrafında tasarlanmıştır
- Farklı işlemleri temsil etmek için farklı HTTP yöntemleri kullanılmıştır
- URL yapısı nettir, çalışılan kaynağı belirtir
Bu tasarım yaklaşımı, API'yi daha sezgisel ve öz açıklamalı hale getirir ve geliştiricilerin her uç noktanın işlevini kolayca anlamalarını sağlar.
RPC: "Sadece POST"un Arkasındaki API Tarzını Anlamak#
RPC (Remote Procedure Call) tarzı API tasarımının amacı, uzak hizmet çağrılarını yerel fonksiyonları çağırmak kadar basit hale getirmektir.
İlginç bir şekilde, "sadece POST"u savunanlar aslında RPC tarzını anlatıyor olabilirler.
RESTful API'lere kıyasla, RPC daha çok işlemin kendisine odaklanır, kaynağa değil. Bu nedenle RPC tarzı API'ler genellikle "fiil + nesne" formunu kullanır, örneğin "getProduct(productId)" veya "createUser(userData)" gibi.
Birçok RPC uygulamasında, tüm işlemler genellikle aynı uç noktaya POST istekleri olarak gönderilir ve belirli işlem ve parametreler talep gövdesinde belirtilir. Bu nedenle, "sadece POST" fikri aslında RPC'ye REST'tan daha yakındır.
Örneğin, HTTP'ye dayalı bir RPC tarzı "üretimi alma" isteği şu şekilde görünebilir:
Modern RPC çerçeveleri, örneğin gRPC, daha güçlü ve verimli uygulamalar sunar. Bu örneği kullanarak RPC tarzını gösterelim:
Öncelikle, hizmeti ve mesaj formatını tanımlıyoruz (Protocol Buffers kullanarak):
Daha sonra, bu hizmeti Node.js istemcisinde kullanmak yerel bir fonksiyonu çağırmak kadar basittir:
Bu RPC tarzı örnekte şunları görebiliriz:
- Hizmet tanımı, mevcut tüm işlemleri açık bir şekilde listeler (bu basitleştirilmiş örnekte, "GetArticle" ve "CreateArticle").
- Her operasyon için net bir şekilde tanımlanmış istek ve yanıt türleri vardır.
- İstemci kodu, bir yerel asenkron fonksiyon çağırmak gibi görünüyor, sonucu beklemek için "await" kullanılır, bu da ağ iletişiminin karmaşıklığını daha da gizler.
- Manuel olarak HTTP istekleri oluşturmaya veya JSON yanıtlarını analiz etmeye gerek yoktur.
Alt katmanda hala HTTP/2 taşıma protokolü olarak kullanılabilir olsa da, RPC çerçeveleri (ör. gRPC) geliştiricilere uzak çağrıları yerel fonksiyon çağrıları gibi görünmesini ve hissedilmesini sağlayan bir soyutlama katmanı sağlar.
Bu nedenle, "sadece POST" ve RESTful API'lar hakkındaki tartışmaların çoğunun esasen bu iki API tarzı hakkında olması gerektiğini görebiliriz: REST ve RPC. Ancak, kilit nokta, bu iki stilin her birinin kendi uygulanabilir senaryolarının olduğunun tanınması gerektiğidir ve tercih, şahsi tercihlere değil, projenin özel ihtiyaçlarına dayanderilmelidir.
REST ve RPC: Mutlak Üstünlük veya Aşağılık Yoktur#
Artık REST ve RPC arasındaki farkları anladığımıza göre, onların sırasıyla uygun senaryolarını inceleyelim:
- REST şu durumlara uygundur:
- Kaynak odaklı uygulamalar (içerik yönetim sistemleri, blog platformları, e-ticaret siteleri gibi)
- İyi önbellek desteği gerektiren senaryolar (GET istekleri doğal olarak önbelleklenebilir)
- HTTP semantiklerinden yararlanmak isteyen projeler (uygun durum kodları kullanımı gibi)
- İyi keşfedilebilirlik ve kendi kendini açıklama gerektiren kamu API'ları
- RPC şu durumlara uygundur:
- Eylem odaklı uygulamalar (karmaşık veri işleme işlemleri, iş akışı kontrolü gibi)
- Yüksek performans ve düşük gecikme gerektiren sistemler (gerçek zamanlı ticaret sistemleri gibi)
- Mikro hizmetler arasında iletişim (daha esnek parametre geçişi gerekebilir)
- İşlemler basit bir şekilde CRUD (Create, Read, Update, Delete) işlemlerine eşlenemediğinde
Stil tercihi, belirli ihtiyaçlarınıza bağlı olmalıdır. Bazı durumlarda, aynı sistemde bu iki stilin bir karışımını bile kullanabilirsiniz, böylece farklı bölümlerin ihtiyaçlarını karşılayabilirsiniz.
Sonuç#
- API tasarımının özü, belirli bir yöntem veya stile bağlı kalmak yerine açıklık, tutarlılık, genişletilebilirlik ve verimlilik üzerine odaklanır.
- Hem RESTful hem de RPC olgun API tasarım paradigmalardır. Aralarındaki seçim projenin gereksinimlerine göre yapılmalıdır, kişisel tercihlere değil.
- Eğer "sadece POST" kullanmaya karar verirseniz, API'nizi RPC tarzına göre tasarlayın. RESTful gibi, bu da endüstride yaygın olarak kullanılan bir API spesifikasyonudur, ancak uygun senaryolarda kullanılmalıdır.
- Yüzeysel teknik detaylarıyla kafanız karışmasın. Önemli olan API'nizin kullanıcılarınıza ve iş ihtiyaçlarınıza etkin bir şekilde hizmet edip edememesidir.
- API tasarlarken, hangi HTTP yöntemini kullanacağınızı düşünerek vakit harcamak yerine, kaynak modeliniz, iş mantığınız ve kullanıcı ihtiyaçlarınız hakkında daha fazla düşünün.
Bu anlamsız tartışmalardan dikkatimiz dağılmasın ve gerçekten harika API'ler tasarlamaya odaklanalım. Sonuçta, teknoloji sorunları çözmek içindir, yaratmak için değil.
