E-ticaret sitenizde bir sipariş düştüğünde kargo firmasına gönderi kaydı açılması, stok bilgisinin pazaryerine aktarılması ya da faturanın muhasebe programına geçmesi, arka planda iki yazılımın birbiriyle konuşmasıyla olur. Bu konuşmanın en yaygın dili API'lerdir ve web'deki API'lerin önemli bir kısmı REST tarzında tasarlanır. Bu yazıda RESTful API'nin ne olduğunu, temel ilkelerini ve bir işletme sahibinin entegrasyon konuşurken bilmesi gerekenleri anlatıyoruz.
RESTful API nedir?
API (Application Programming Interface), bir yazılımın başka bir yazılıma hangi veriyi, hangi kurallarla sunduğunu belirleyen arayüzdür. REST (Representational State Transfer) ise bu arayüzün web üzerinde nasıl tasarlanacağını anlatan bir mimari tarzdır. REST ilkelerine uyan API'ye RESTful API denir: istemci bir adrese HTTP isteği gönderir, sunucu da o kaynağın temsilini, çoğunlukla JSON biçiminde, geri döndürür.
Örnek: Bir mağaza API'sinde GET /products/125 isteği 125 numaralı ürünün bilgisini getirir, PATCH /products/125 isteği yalnız fiyatını ya da stok sayısını günceller. Adres "ne" üzerinde işlem yapıldığını, metot ise "ne yapıldığını" söyler.
REST'in 6 temel ilkesi
Roy Fielding'in California Üniversitesi Irvine'de 2000 yılında tamamladığı doktora tezinin 5. bölümü, REST'i bir dizi kısıt olarak tanımlar. Bir API'nin "RESTful" sayılması bu kısıtlara ne kadar uyduğuna bağlıdır:
- İstemci-sunucu ayrımı Arayüz (site, mobil uygulama) ile veriyi tutan sunucu birbirinden bağımsız gelişebilir.
- Durumsuzluk (stateless) Her istek, anlaşılması için gereken tüm bilgiyi kendisi taşır; sunucu önceki istekleri hatırlamak zorunda değildir.
- Önbelleklenebilirlik Yanıtlar önbelleğe alınıp alınamayacaklarını belirtir; böylece tekrar eden istekler hızlanır.
- Tek biçimli arayüz Kaynaklar adresle tanımlanır, temsiller üzerinden değiştirilir, mesajlar kendini açıklar ve bağlantılar uygulamanın akışını yönlendirir.
- Katmanlı sistem İstemci, arada vekil sunucu, yük dengeleyici ya da CDN olup olmadığını bilmek zorunda değildir.
- İsteğe bağlı kod Sunucu gerektiğinde istemciye çalıştırılabilir kod gönderebilir; bu, altı ilkeden tek isteğe bağlı olanıdır.
HTTP metotları: GET, POST, PUT, PATCH, DELETE
| Metot | Ne yapar? | Güvenli mi? | Idempotent mi? |
|---|---|---|---|
| GET | Kaynağı okur (ör. ürün listesini getirir) | Evet | Evet |
| POST | Yeni kaynak oluşturur ya da işlem başlatır (ör. sipariş açar) | Hayır | Hayır |
| PUT | Kaynağı gönderilen temsille tamamen değiştirir | Hayır | Evet |
| PATCH | Kaynağın yalnız bir kısmını günceller (ör. stok adedi) | Hayır | Hayır |
| DELETE | Kaynağı siler | Hayır | Evet |
Idempotent kavramı entegrasyonlarda pratik bir önem taşır. Ağ kesildiği için yeniden gönderilen bir PUT isteği sorun çıkarmaz, ama yeniden gönderilen bir POST isteği aynı siparişi iki kez açabilir. İyi tasarlanmış entegrasyonlar bu yüzden sipariş gibi işlemlerde tekrar kontrolü yapar. Sunucu her yanıtta bir durum kodu döndürür: 200 başarılı, 201 oluşturuldu, 400 hatalı istek, 401 kimlik doğrulanmadı, 404 kaynak bulunamadı, 500 sunucu hatası anlamına gelir.
REST mi GraphQL mi? E-ticaret platformlarında durum
REST tek seçenek değildir. GraphQL'de istemci tek bir adrese, hangi alanları istediğini belirten bir sorgu gönderir; böylece gereğinden fazla ya da eksik veri gelmez. E-ticaret platformlarının tercihi entegrasyon yaptırırken önemlidir:
- Shopify: REST Admin API, 1 Ekim 2024 itibarıyla "eski" (legacy) API sayılıyor. 1 Nisan 2025'ten bu yana yeni herkese açık uygulamaların yalnız GraphQL Admin API ile geliştirilmesi gerekiyor.
- ikas: Geliştirici portalındaki Admin API, GraphQL uç noktası üzerinden çalışıyor.
- IdeaSoft: Admin API için geliştirici belgelerini apidoc.ideasoft.dev adresinde yayımlıyor; özel entegrasyonlar bu belgeler üzerinden kurgulanıyor.
- Kargo, ödeme ve muhasebe servisleri: Çoğu REST ya da ona yakın HTTP tabanlı API sunar; hangi tarzı kullandığını her servisin kendi belgesinden kontrol edin.
Dikkat: API anahtarları ve erişim belirteçleri (token) mağazanızın anahtarıdır. Bunları e-postayla paylaşmayın, sitenin herkese açık koduna gömmeyin, entegrasyon için yalnız gereken izinleri verin ve bir çalışan ya da ajans işi bıraktığında anahtarları yenileyin. API isteklerinin HTTPS üzerinden yapıldığından emin olun.
Entegrasyon yaptırmadan önce sorulacak sorular
- Bağlanacak iki sistemin de belgelenmiş bir API'si var mı, REST mi GraphQL mi?
- Hangi veriler, hangi yönde ve ne sıklıkla akacak (ürün, stok, fiyat, sipariş, fatura)?
- API'nin istek sınırı (rate limit) var mı, yoğun kampanya günlerinde yeterli mi?
- Hata olduğunda kim, nasıl haberdar olacak; başarısız istekler yeniden deneniyor mu?
- Hazır bir entegrasyon modülü varken özel geliştirme gerçekten gerekli mi?
API her zaman gerekmez; tedarikçiden ürün çekmek için XML ya da Excel ile aktarım çoğu zaman yeterlidir. Bu yöntemleri XML ile e-ticaret ve XML/Excel ürün aktarım robotu yazılarımızda, kargo tarafını kargo entegrasyonları rehberimizde anlattık. Platform seçiminde entegrasyon esnekliğini de tartıyorsanız ikas ve IdeaSoft teknik karşılaştırmamız yardımcı olur. IdeaSoft, ikas, Ticimax, T-Soft, Shopify ve WooCommerce kurulumlarında ödeme, kargo ve pazaryeri bağlantılarını e-ticaret kurulum hizmetimizin parçası olarak yapıyoruz. Kendi sistemlerinizle özel bir bağlantı gerekiyorsa özel yazılım geliştirme ve API entegrasyonu hizmetimize bakabilirsiniz.
Sık sorulan sorular
REST API ile RESTful API aynı şey mi?
Günlük kullanımda aynı anlamda kullanılır. Tam anlamıyla RESTful API, REST mimari tarzının kısıtlarına uyan API demektir; HTTP kullanan her API bu kısıtların hepsine uymaz.
RESTful API hangi veri biçimini kullanır?
REST belli bir biçim şart koşmaz; kaynaklar farklı temsillerle sunulabilir. Günümüzde en yaygın biçim JSON'dur, bazı eski servisler XML kullanmaya devam eder.
PUT ile PATCH arasındaki fark nedir?
PUT kaynağın tamamını gönderilen temsille değiştirir ve idempotenttir. PATCH yalnız belirtilen alanları günceller; RFC 5789'a göre güvenli ya da idempotent değildir.
API entegrasyonu için yazılımcı gerekir mi?
Hazır entegrasyon modülü olan bağlantılar panelden birkaç ayarla kurulabilir. İki sistem arasında hazır modül yoksa API belgelerine göre özel geliştirme gerekir.
Kaynaklar
- Roy T. Fielding, Architectural Styles and the Design of Network-based Software Architectures, Bölüm 5 (2000) (28.09.2026)
- RFC 9110, HTTP Semantics (28.09.2026)
- Shopify, REST Admin API reference (28.09.2026)
- ikas Developer Portal (28.09.2026)
- IdeaSoft Admin API belgeleri (28.09.2026)
