REST API Tasarım İncelikleri
Sayfayı kopyala
💡 Özet (TL;DR):
- Giriş: Web uygulamaları, mobil cihazlar ve diğer üçüncü parti servisler için ortak bir arka uç (backend) mimarisi kurgularken RESTful API tasarım standartları hayati önem taşır.
- Serinin Amacı: API mimarisi kurarken çıktı formatı, URI yapısı, güvenlik, hata yönetimi ve kimlik doğrulama gibi temel unsurları standartlaştırmak.
- Temel Tercihler: Özel bir kısıtlama olmadığı sürece modern web standartlarına en uygun veri transfer formatı olarak JSON tercih edilmelidir.
RESTful API Tasarımının İnceliklerini Öğrenmeye Kimin İhtiyacı Var? Bu Yazı Kimin İçin?
Tek tabanca çalışan bir geliştiriciysen ve küçük-orta büyüklükte klasik bir web sitesi oluşturuyorsan bir REST API'ye ihtiyacın olmayacaktır; bildiğin monolitik yöntemlerle devam edebilirsin.
Fakat web sitenizin, mobil cihazlarınızın ve belki de diğer harici servislerin veri tüketeceği ortak bir arka uç (backend) tasarlaman gerekiyorsa, o zaman REST API tasarımının inceliklerini öğrenmen gerekir.
Geniş kapsamlı bir konu olması nedeniyle, konuyu mantıklı parçalara ayırarak incelemek çok daha faydalı olacaktır.
REST API HTTP Metotları ve Kullanım Amaçları
| HTTP Metodu | İşlem Türü (CRUD) | Açıklama | Güvenli (Safe)? | Idempotent? |
|---|---|---|---|---|
| GET | Read (Oku) | Belirtilen kaynağı veya koleksiyonu sorgular. | Evet | Evet |
| POST | Create (Oluştur) | Yeni bir kaynak oluşturur. | Hayır | Hayır |
| PUT | Update (Güncelle) | Belirtilen kaynağı tamamen yenisiyle değiştirir. | Hayır | Evet |
| PATCH | Update (Kısmi Güncelle) | Kaynağın sadece belirli alanlarını günceller. | Hayır | Hayır |
| DELETE | Delete (Sil) | Belirtilen kaynağı siler. | Hayır | Evet |
Serinin Tamamı
Aşağıdaki başlıklar altında RESTful API tasarımını parça parça ele alacağız. İlk iki başlık bu yazı içerisinde yer alırken, diğer başlıklara ilgili bağlantılardan ulaşabilirsiniz:
- REST API Temelleri
- REST API Çıktı Formatı Ne Olmalı?
- REST API URI Yapısı Nasıl Olmalı?
- REST API HATEOAS Kavramı Nedir?
- REST API Kimlik Doğrulama Nasıl Yapılır? (Authentication)
- REST API Hata Yönetimi Nasıl Yapılır? (Error Handling)
- REST API Güvenliği Nasıl Sağlanır? (Security)
- REST API Dokümantasyon ve Testi Nasıl Yapılır?
- Örnek REST API Projesi
Dürüst olacağım, bu bilgilerin çoğunun kaynağı ben değilim. Birkaç sene öncesine kadar API'lerin sadece tüketicisiydim. Gün gelip bir API yazmam gerektiğinde bu konuda bol bol araştırma yapıp notlar aldım; bu yazacaklarım da o notlarımın derlenip toplanmış, biraz da kendi deneyimlerimi kattığım hâlidir.
Farklı Yaklaşımlar
Burada anlatacağım başlıkların çoğu için farklı yaklaşımlar veya yöntemler olabilir. Hatta sektördeki dev firmaları incelediğinizde buradaki standartlarla uyumsuz noktalar olduğunu, kendi şirket içi pratiklerini benimsediklerini görebilirsiniz. Benim anlatacaklarım; yaptığım araştırmalar ve denemeler sonrasında edindiğim, "ben bir REST API tasarlasam böyle yaparım" dediğim en iyi pratikler (best practices) olacak.
Mimariden Bağımsız Tasarım
Kullanılan programlama dili, veritabanı veya sunucu altyapısı doğrudan API tasarımının dışındadır; bunlar bütçe, ekip yetkinliği ve mevcut sistemin ihtiyaçlarına göre belirlenir. O nedenle işin kodlama ve sunucu kısımlarını atlayıp doğrudan API arayüz tasarımını ilgilendiren bölümlere odaklanacağız.
Daha önce yazdığım RESTful API Bileşenleri başlığında bu konudaki kişisel teknoloji tercihlerimi belirtmiştim.
REST API Temelleri
RESTful API tasarımı ile belirli kaynaklar sunup bunları istemcilerin kullanımına açmış olursunuz. Monolitik sitelerde AJAX ile backend'e sorgu atıp gelen sonuçlara göre arayüzü güncelleriz ya; RESTful API de herhangi bir istemcinin (web, mobil, IoT) bize HTTP üzerinden istek göndermesi, bizim de o istemcinin anlayacağı standart bir dille yanıt dönmemizdir.
API'niz kaynaklar (örneğin yazar) veya bu kaynaklardan oluşan koleksiyonları (yazarlar) paylaşıma açar, oluşturur, günceller ve siler.
Bu kaynaklarla işlem yapmak için önceden belirlenmiş uç nokta (endpoint) adreslerine GET, POST, PUT, PATCH ve DELETE gibi klasik HTTP metotları ile istek gönderilir.
Aslına bakarsanız keşke her proje sadece saf bir RESTful API'den oluşsa. Standart bir veri modeli gelecek, o veriyle işlemler yapılıp standart bir formatta çıktı verilecek. Full-stack bir monolitik uygulamayla uğraşmaktan çok daha zahmetsiz ve temiz bir süreçtir. :)
Çıktı Formatı Ne Olmalı?
API'nizin çıktı formatı JSON, CSV, XML, RSS veya HTML olabilir. İhtiyaçların sınırsız olduğu yazılım dünyasında şüphesiz bunlara yönelik çözümler de çok çeşitlidir. Ancak genel kullanıma açık modern bir REST API tasarlıyorsanız muhtemelen JSON tercih edeceksiniz.
Özel veya zorlayıcı bir sistem kısıtlaması yoksa, hafifliği ve JavaScript ekosistemiyle tam uyumu nedeniyle çıktı formatı olarak JSON kullanmanızı kesinlikle tavsiye ederim.
Serinin bir sonraki yazısında, RESTful API'lerde uç nokta adreslerinin (URI) nasıl belirlenmesi gerektiği üzerinde duracağız:
Bu Yazıda Yapılan Değişiklikler
- 11.05.2022: Yazı özeti düzenlendi.
- 21.06.2026: REST API marka standartları, imla hataları (altyapı, metotları, testi vb.) ve cümle içi mükerrer kelimeler düzeltildi. Cümlenin sonundaki çift noktalama işaretleri temizlendi. Giriş için TL;DR özet paneli ve HTTP metotlarının CRUD/Idempotent özelliklerini gösteren bir referans tablosu eklenerek yazı zenginleştirildi.
