REST API Nedir, Nasıl Tasarlanır?
REST, web üzerindeki API'lerin en yaygın tasarım yaklaşımıdır. Kaynak mantığını, HTTP metotlarını ve iyi tasarımın kurallarını örneklerle anlatıyorum.
İçindekiler
Bir yazılımcıdan teklif aldığınızda “arka uç REST API olarak yazılacak” cümlesini görmüş olabilirsiniz. REST API nedir, neden bu kadar yaygındır ve iyi tasarlanmış bir REST API ile özensiz yazılmış olanı nasıl ayırt edersiniz? REST (Representational State Transfer), web’in zaten kullandığı HTTP protokolünün kurallarını izleyerek sistemlerin veri alışverişi yapmasını sağlayan bir mimari yaklaşımdır. Bir kütüphane ya da ürün değil, bir tasarım tarzıdır. Bu yazıda bu tarzın temel ilkelerini ve pratikte nasıl uygulandığını anlatacağım.
API kavramına yabancıysanız önce API nedir, işletmeler için anlaşılır açıklama yazısına göz atmanızı öneririm.
REST API nedir? Kaynak mantığı
REST’in merkezinde kaynak (resource) kavramı vardır. Kaynak, sistemde yönetilen her türlü şeydir: ürünler, siparişler, müşteriler, randevular. Her kaynağın kendine ait bir adresi (URL) bulunur ve bu adres üzerinde HTTP metotlarıyla işlem yapılır.
Örneğin bir e-ticaret sisteminde /products tüm ürünleri, /products/42 ise 42 numaralı ürünü temsil eder. Adres “ne” üzerinde çalıştığınızı, HTTP metodu ise “ne yapmak” istediğinizi söyler. Bu ayrım REST’i hem okunabilir hem de öngörülebilir kılar.
HTTP metotları ve anlamları
REST tasarımında her metot belirli bir işi anlatır. Aynı kuralı tutarlı uygulamak, API’yi kullanan herkesin işini kolaylaştırır.
| Metot | Ne yapar? | Örnek |
|---|---|---|
| GET | Veriyi okur, değiştirmez | GET /orders/15 (siparişi getir) |
| POST | Yeni kayıt oluşturur | POST /orders (yeni sipariş) |
| PUT | Kaydı bütünüyle günceller | PUT /customers/7 |
| PATCH | Kaydın bir kısmını günceller | PATCH /orders/15 (yalnızca durum) |
| DELETE | Kaydı siler | DELETE /cart/items/3 |
Sık yapılan bir hata, her şeyi POST ile yapmak ya da adrese fiil koymaktır (/getOrder, /deleteProduct gibi). REST yaklaşımında fiil adreste değil, metotta durur.
REST’in temel ilkeleri
REST’i REST yapan birkaç ilke vardır. Bunları bilmek, teklif ya da teknik doküman okurken neyin doğru kurgulandığını anlamanıza yardımcı olur:
- Durumsuzluk (stateless): Her istek kendi içinde yeterli bilgiyi taşır. Sunucu, önceki isteği hatırlamak zorunda değildir; kimlik bilgisi her istekte gönderilir. Bu, sistemin yatayda büyütülmesini kolaylaştırır.
- İstemci-sunucu ayrımı: Arayüz (web sitesi, mobil uygulama) ile veri katmanı birbirinden bağımsız gelişebilir.
- Önbelleklenebilirlik: Cevaplar, önbelleğe alınıp alınamayacağını belirtebilir. Sık değişmeyen veriler için bu, hızı ciddi biçimde artırır.
- Tek tip arayüz: Tüm kaynaklar aynı kurallarla adreslenir ve işlenir.
Durum kodları: API’nin konuşma dili
İyi bir REST API, cevabın ne anlama geldiğini HTTP durum koduyla açıkça bildirir. Her cevaba “200 OK” dönüp hatayı metnin içine gömmek, hata ayıklamayı zorlaştırır. En sık kullanılan kodlar şunlardır:
- 200 OK: İstek başarılı.
- 201 Created: Yeni kayıt oluşturuldu.
- 400 Bad Request: Gönderilen veri hatalı veya eksik.
- 401 Unauthorized: Kimlik doğrulanmadı.
- 403 Forbidden: Kimlik doğru ama bu işleme yetki yok.
- 404 Not Found: Kaynak bulunamadı.
- 500 Internal Server Error: Sunucu tarafında beklenmeyen bir hata oluştu.
İyi bir REST API nasıl tasarlanır?
Tasarım, kodlamadan önce yapılan ve sonradan değiştirmesi en pahalı olan aşamadır. Bir REST API planlarken şu kurallara dikkat ediyorum:
Tutarlı adlandırma
Kaynak adları çoğul isim olur (/orders, /customers). İlişkili kaynaklar iç içe gösterilebilir: /customers/7/orders, 7 numaralı müşterinin siparişleridir. Alan adlarında tek bir yazım stili seçilir ve her yerde aynı kullanılır.
Sayfalama, filtreleme ve sıralama
Binlerce kaydı tek seferde döndürmek hem sunucuyu yorar hem uygulamayı yavaşlatır. Liste uç noktalarında sayfalama ve filtre parametreleri baştan planlanır:
GET /orders?status=shipped&page=2&per_page=20&sort=-created_atBu istek, kargoya verilmiş siparişlerin ikinci sayfasını, en yeniden eskiye doğru, sayfa başına 20 kayıt olacak şekilde getirir.
Anlaşılır hata mesajları
Hata cevabı, hangi alanda ne sorun olduğunu söylemelidir. “Geçersiz istek” yerine “telefon alanı boş bırakılamaz” demek, mobil uygulamayı yazan ekibin saatlerini kurtarır.
Sürümleme ve dokümantasyon
API yayına girdikten sonra onu kullanan uygulamaları bozmadan değiştirebilmek için sürüm planı gerekir. Bu konuyu API versiyonlama yazısında ayrıca ele aldım. Ayrıca her uç noktanın ne beklediği ve ne döndürdüğü yazılı olmalıdır; bunun için API dokümantasyonu rehberine bakabilirsiniz.
REST API nerelerde karşınıza çıkar?
REST API nedir diye sorduğunuzda aslında her gün kullandığınız pek çok sistemi tarif etmiş olursunuz.WordPress’in kendisi bile yerleşik bir REST API ile gelir; bu sayede bir WordPress sitesinin içeriği mobil uygulamada ya da başka bir sistemde kullanılabilir. Altın fiyatlarını gösteren bir eklentide, fiyatlar önbellekli bir REST API’den sunulur ve aynı uç noktayı mobil uygulama da kullanır. Tele-sağlık, randevu, stok takibi gibi işletmeye özel yazılımların neredeyse tamamında da arka uç ile arayüz REST API üzerinden konuşur.
Bu işi nasıl birlikte yaparız?
Kendi sisteminiz için bir REST API kurmak ya da mevcut API’nizi elden geçirmek istiyorsanız genellikle şu adımları izliyorum:
- Veri modelini çıkarma: Hangi kaynakların (ürün, sipariş, üye) olduğunu ve aralarındaki ilişkileri sizinle birlikte belirleriz.
- Uç nokta taslağı ve teklif: Adresleri, metotları ve yetki kurallarını içeren bir taslak hazırlar, kapsamı netleştirerek teklif veririm.
- Geliştirme ve test: Her uç noktayı hem doğru hem hatalı verilerle test eder, durum kodlarının tutarlı olduğunu kontrol ederim.
- Dokümantasyon ve teslim: API’yi başka bir geliştiricinin de anlayabileceği şekilde belgeleyip kaynak koduyla birlikte teslim ederim.
Projenizi konuşmak için iletişim sayfasından bana ulaşabilirsiniz.
Sık sorulan sorular
REST API ile RESTful API arasında fark var mı?
Günlük kullanımda aynı anlamdadır. RESTful, REST ilkelerine uyan API’yi tarif eden bir sıfattır.
REST API yalnızca JSON mu döndürür?
Hayır, REST belirli bir veri biçimi şart koşmaz. Ancak bugün web ve mobil uygulamalarda en yaygın biçim JSON’dur; okunması ve işlenmesi kolaydır.
REST API güvenli midir?
Güvenlik REST’in kendisinden değil, uygulamadan gelir. HTTPS, kimlik doğrulama, yetki kontrolü ve istek sınırlaması doğru kurulduğunda REST API güvenle kullanılabilir.
Her proje için REST mi tercih edilmeli?
Çoğu işletme projesi için REST yeterli ve pratiktir. Çok farklı ekranların çok farklı veri kombinasyonları istediği durumlarda GraphQL gibi alternatifler değerlendirilebilir.
Sonuç
REST API nedir sorusunun özü şudur: kaynakları anlamlı adreslerle, işlemleri HTTP metotlarıyla ve sonuçları durum kodlarıyla ifade eden, öngörülebilir bir tasarım yaklaşımı. Baştan doğru tasarlanan bir REST API, yıllarca web sitenizi, mobil uygulamanızı ve entegrasyonlarınızı taşır. Projenize uygun yapıyı birlikte planlamak isterseniz bana yazabilirsiniz.