API Nedir? REST API, Web Servis ve Webhook Farkı

API nedir sorusunun kısa cevabı şu: API (Application Programming Interface, Türkçesiyle uygulama programlama arayüzü), iki yazılımın birbirinden veri istemesini ve birbirine iş yaptırmasını sağlayan tanımlı kurallar bütünüdür. Ödeme sayfanızın bankaya ya da ödeme kuruluşuna bağlanması, kargo takip numarasının siparişe kendiliğinden düşmesi ya da web sitenizdeki formun CRM'de kayıt açması API'ler sayesinde olur. Kullanıcı API'yi görmez; yalnız iki sistemin sorunsuz konuştuğunu fark eder.

API nedir, nasıl çalışır?

API'yi bir banka gişesine benzetebilirsiniz. Kasaya kendiniz girmezsiniz; gişeye belli bir formla gelir, kimliğinizi gösterir ve kuralların izin verdiği işlemi yaptırırsınız. API de bir sistemin iç yapısını dışarıya açmadan, yalnız izin verilen işlemleri tanımlı bir kapıdan sunar.

Bir API bağlantısında temelde dört parça vardır:

• İstek (request): Bir sistemin diğerinden bir şey istemesi. "Bu siparişin kargo durumunu ver" gibi.
• Uç nokta (endpoint): İsteğin gönderildiği adres. Her işlem için ayrı bir adres tanımlanır.
• Kimlik doğrulama: İsteği yapanın yetkili olduğunu gösteren anahtar ya da belirteç (token). API anahtarı ve OAuth yaygın yöntemlerdir.
• Yanıt (response): Karşı sistemin cevabı. Genellikle JSON ya da XML biçiminde veri ve işlemin başarılı olup olmadığını gösteren bir durum kodu içerir.

Web üzerinden çalışan API'lerde, özellikle REST'te, istek türleri de standarttır: veri okumak için GET, yeni kayıt oluşturmak için POST, güncellemek için PUT ya da PATCH, silmek için DELETE kullanılır. Bu ayrıntıları ezberlemeniz gerekmez. Ama bir entegrasyon teklifinde "karşı sistemin API'si yalnız okumaya izin veriyor" gibi bir cümle gördüğünüzde, o sisteme sipariş ya da kayıt gönderemeyeceğinizi anlamak işinize yarar.

API ne demek, neden "arayüz" deniyor?

Buradaki "arayüz" ekran anlamına gelmez. İki yazılım arasındaki anlaşma noktası, yani hangi isteğin hangi biçimde yapılacağını ve hangi cevabın döneceğini belirleyen sözleşme kastedilir. Kullanıcı arayüzü insanlar için, programlama arayüzü yazılımlar için tasarlanır.

API türleri: REST, SOAP ve GraphQL

Günlük kullanımda en çok üç yaklaşımla karşılaşırsınız. Aralarındaki fark, isteklerin nasıl yazıldığı ve verinin hangi biçimde taşındığıdır.

Tür	Nasıl çalışır	Veri biçimi	Nerede karşınıza çıkar
REST API	Web adresleri ve standart istek türleriyle verilere erişir	Çoğunlukla JSON	Bulut yazılımlar, pazaryerleri, ödeme ve kargo servisleri
SOAP web servis	Kuralları önceden sıkı biçimde tanımlanmış mesajlaşma	XML	Eski kurumsal sistemler, bazı banka ve resmî kurum entegrasyonları
GraphQL	İstemci hangi alanları istediğini tek sorguda belirtir	JSON	Farklı ekranlar için farklı veri isteyen web ve mobil uygulamalar

REST API nedir?

REST, web'in çalışma mantığını kullanan bir mimari yaklaşımdır. Her veri türü (müşteri, sipariş, ürün) bir adresle temsil edilir ve bu adrese standart istek türleriyle erişilir. Hafif, okunması kolay ve yaygın olduğu için yeni geliştirilen API'lerde sık tercih edilir.

Web servis nedir, API'den farkı ne?

Web servis, ağ üzerinden erişilen API'dir. Her web servis bir API'dir, ama her API web servis değildir. Örneğin bir işletim sisteminin uygulamalara sunduğu arayüz de bir API'dir, ancak ağ üzerinden çalışmaz. Türkiye'de "web servis" ifadesi çoğu zaman XML tabanlı SOAP servisleri için kullanılır; bir entegratör "web servis üzerinden bağlanıyoruz" dediğinde hangi yaklaşımın kastedildiğini sormak yerinde olur.

Webhook nedir, API'den farkı ne?

Webhook, bir sistemde bir olay gerçekleştiğinde diğer sisteme kendiliğinden haber gönderilmesidir. Klasik API kullanımında siz sorarsınız: "Ödeme onaylandı mı?" Webhook'ta sormanıza gerek kalmaz; ödeme onaylandığında ödeme kuruluşu bildirimi sizin sisteminizdeki belirli bir adrese kendisi gönderir.

Ölçüt	Klasik API isteği	Webhook
Kim başlatır	Bilgiye ihtiyacı olan sistem	Olayın gerçekleştiği sistem
Ne zaman çalışır	İstek gönderildiğinde	Olay gerçekleştiğinde
Tipik kullanım	Ürün listesini çekmek, stok sorgulamak	Ödeme onayı, kargo teslimi, form gönderimi
Dikkat edilecek nokta	Çok sık sorgulama gereksiz yük oluşturur	Bildirimin gerçekten karşı sistemden geldiği doğrulanmalı

Webhook'lar genellikle API ile birlikte kullanılır. Bildirim yalnız "sipariş güncellendi" der; ayrıntıyı almak için API'ye ayrıca istek yapılır. Webhook kurarken bildirimin imzasını doğrulamak, aynı bildirim iki kez gelirse işlemi tekrarlamamak ve karşı sisteme ulaşılamadığında yeniden denemek gibi ayrıntılar önemlidir.

İşletmelerde API örnekleri

API'ler çoğu işletmede fark edilmeden çalışır. Sık karşılaşılan örnekler:

• E-ticaret ve ödeme: Sepetteki tutar ödeme kuruluşuna iletilir, sonuç siteye döner.
• Kargo: Gönderi kaydı açılır, takip numarası ve teslim durumu siparişe işlenir.
• E-fatura ve e-arşiv: Faturalar çoğu işletmede bir entegratör firmanın servisi üzerinden düzenlenir ve iletilir.
• Pazaryerleri: Ürün, fiyat ve stok bilgisi pazaryerine gönderilir, siparişler geri alınır.
• Web formu ve CRM: Sitedeki talep formu doldurulduğunda CRM'de yeni bir kayıt açılır.
• ERP ve diğer sistemler: Stok, cari hesap ve sipariş bilgisi ERP ile e-ticaret sitesi ya da CRM arasında eşitlenir. ERP'nin diğer yazılımlarla ilişkisini ayrı bir yazıda anlattık.
• Bildirim servisleri: SMS ve e-posta gönderimi çoğunlukla bir servis sağlayıcının API'si üzerinden yapılır.

Bir siparişin API'lerle yolculuğu

Bir e-ticaret siparişi, arka planda birkaç API ve webhook'un sırayla çalışmasıyla tamamlanır:

1. Müşteri ödeme bilgisini girer; site, tutarı ödeme kuruluşunun API'sine iletir.
2. Ödeme onaylandığında ödeme kuruluşu, webhook ile sitenize haber verir.
3. Sipariş, API üzerinden ERP ya da muhasebe programına aktarılır ve stok düşülür.
4. Kargo firmasının API'siyle gönderi kaydı açılır, takip numarası siparişe yazılır.
5. Fatura, entegratörün servisi üzerinden e-arşiv ya da e-fatura olarak düzenlenir ve müşteriye iletilir.
6. Paket teslim edildiğinde kargo firması durumu webhook ile bildirir, sipariş kapanır.

Müşteri bu adımların hiçbirini görmez. Ancak zincirin bir halkası koptuğunda, örneğin kargo API'si yanıt vermediğinde, siparişin nerede takıldığını görebilmek için her bağlantının izlenmesi ve hata durumunda ne yapılacağının tanımlı olması gerekir.

Bu bağlantıların her biri bir entegrasyon projesidir. Hangi verinin hangi yönde akacağını, hata durumunda ne olacağını ve kimin sorumlu olduğunu önceden netleştirmek için yazılım entegrasyonu öncesi sorulacak soruları okuyabilirsiniz.

Bir API'yi değerlendirirken sorulacak sorular

• Dokümantasyonu açık ve güncel mi?
• Canlı sisteme dokunmadan deneme yapılabilecek bir test ortamı var mı?
• Belli bir sürede yapılabilecek istek sayısında sınır var mı?
• Kullanım ücretli mi, ücret istek sayısına göre artıyor mu?
• API'nin yeni sürümü çıktığında eski sürüm ne kadar süre destekleniyor?
• Sorun çıktığında ulaşılabilecek bir teknik destek kanalı var mı?

Bu soruların cevaplarını teknik şartnamedeki entegrasyon maddelerine eklemek, teklif aşamasında sürprizleri azaltır.

Granobra'da nasıl çalışıyoruz

İstanbul merkezli ekibimizle geliştirdiğimiz özel yazılım, işletmeye özel CRM ve e-ticaret projelerinde bağlanacak sistemleri proje başında sizinle birlikte listeliyoruz. Karşı sistemin API dokümantasyonu, test ortamı ve erişim yetkileri bu listenin parçasıdır. Bu projelerin kapsamını web yazılım ve özel yazılım geliştirme sayfamızda bulabilirsiniz.

Sık sorulan sorular

API kullanmak ücretli mi?

Servis sağlayıcısına göre değişir. Bazı servisler API erişimini abonelik paketine dahil eder, bazıları istek sayısına ya da işlem hacmine göre ücretlendirir. Entegrasyon planlarken bu ücretleri geliştirme maliyetinden ayrı bir kalem olarak hesaba katın.

API güvenli mi?

Güvenlik, API'nin nasıl tasarlandığına ve nasıl kullanıldığına bağlıdır. Şifreli bağlantı (HTTPS), güçlü kimlik doğrulama, yalnız gereken yetkilerin verilmesi ve anahtarların güvenli saklanması temel önlemlerdir. Kişisel veri taşıyan bağlantılarda KVKK yükümlülükleri de ayrıca değerlendirilmelidir.

Web sitemin API ile başka sistemlere bağlanması gerekir mi?

Her site için gerekmez. Siteniz yalnız bilgi sunuyorsa API bağlantısına ihtiyaç duymayabilir. Formlarınızın CRM'e düşmesini ya da ürünlerinizin pazaryerine gitmesini istiyorsanız sitenizin bu sistemlerin API'leriyle konuşması gerekir. Bayilerinizin stok görmesi gibi dışarıya veri açmanız gereken durumlarda ise sitenizin kendi API'si olması gerekebilir.

Hazır yazılım seçerken API'ye bakmak gerekir mi?

Gerekir. Bugün tek başına kullanılacak gibi görünen bir yazılımı yarın muhasebe, e-ticaret ya da CRM ile bağlamak isteyebilirsiniz. API'si olmayan ya da yalnız okumaya izin veren bir ürün, ileride veriyi elle taşımanıza neden olur.

API anahtarı nedir, nasıl korunur?

API anahtarı, bir sistemin API'ye bağlanırken kendini tanıttığı gizli bir koddur ve şifre gibi korunmalıdır. Anahtarı e-postayla açıkça göndermek yerine güvenli bir kanaldan, yalnız entegrasyonu yapan ekiple paylaşın. Ekip değiştiğinde ya da anahtarın sızdığından şüphelendiğinizde anahtarı yenileyin.

Birbiriyle konuşması gereken sistemleriniz varsa bağlantıları Granobra ile birlikte planlayalım. Projenizi konuşmak için teklif formunu doldurun.