API Nedir? Haber Örnekleriyle Ne İşe Yaradığı ve Nasıl Çalıştığı

API (Application Programming Interface, Uygulama Programlama Arayüzü), iki yazılımın birbiriyle önceden belirlenmiş kurallarla konuşmasını sağlayan arayüzdür. Bir yazılım "bana son 10 ekonomi haberini ver" diye istek gönderir, diğeri bu isteği anlar ve sonucu düzenli bir biçimde (çoğunlukla JSON) geri yollar. Kullanıcı ekranda bir düğmeye basarken, arka planda bu konuşma saniyenin küçük bir kısmında tamamlanır.

Yazar Haber Ajansı'nın (YHA) API'sini kendi sitenize bağlamak istiyorsanız kurulum adımları için doğrudan Yazar Haber Ajansı API belgelerine geçebilirsiniz.

API Ne Demek? Restoran Benzetmesi

API'yi anlatmak için en çok kullanılan benzetme restorandır. Siz (müşteri) mutfağa giremezsiniz; garsona menüden sipariş verirsiniz. Garson siparişi mutfağa iletir, hazırlanan yemeği size getirir. Burada:

• Müşteri, veriyi isteyen yazılımdır (örneğin bir haber sitesi).
• Menü, API belgesidir: neyi, hangi biçimde isteyebileceğinizi gösterir.
• Garson, API'nin kendisidir: isteği alır, kuralına uygunsa iletir, sonucu getirir.
• Mutfak, verinin tutulduğu sistemdir (haber ajansının veritabanı).

Müşterinin mutfağın nasıl çalıştığını bilmesi gerekmez. Aynı şekilde bir haber sitesinin, ajansın içerik yönetim sistemini, veritabanı yapısını veya sunucularını bilmesi gerekmez. Yalnızca API'nin "menüsüne" uygun sipariş vermesi yeterlidir. Bu ayrım, iki tarafın birbirini bozmadan bağımsız olarak geliştirilebilmesini sağlar.

API Ne İşe Yarar?

API'ler günlük hayatta kullandığımız neredeyse her dijital hizmetin arkasındadır. Hava durumu uygulaması verisini bir meteoroloji API'sinden, kargo takip ekranı bilgisini kargo firmasının API'sinden, ödeme sayfası onayı bankanın API'sinden alır. Haber dünyasında ise API'nin başlıca kullanımları şunlardır:

1. Otomatik içerik akışı: Haber sitesi, ajansın yeni haberlerini kopyala-yapıştır yapmadan sistemine alır.
2. Filtreleme: Yalnızca belirli kategoriler (spor, ekonomi), belirli bir il veya belirli bir tarih aralığındaki haberler istenebilir.
3. Güncelleme takibi: Bir haber düzeltildiğinde veya geri çekildiğinde site bunu fark edip kendi kopyasını günceller.
4. Çok kanallı yayın: Aynı veri web sitesine, mobil uygulamaya, akıllı ekranlara ve bültenlere aynı anda dağıtılır.
5. Ölçeklenebilirlik: Günde yüzlerce haberi elle taşımak yerine süreç yazılıma devredilir; editör zamanını haberi zenginleştirmeye ayırır.

API Nasıl Çalışır? İstek ve Yanıt Mantığı

Web tabanlı API'lerin büyük çoğunluğu HTTP protokolü üzerinden çalışır; yani tarayıcınızın bir web sayfasını açarken kullandığı protokolün aynısını kullanır. Her konuşma iki parçadan oluşur: istek (request) ve yanıt (response).

Bir istek şu bileşenleri içerir:

Aşağıdaki örnek, kavramı göstermek için hazırlanmış genel bir istektir; uç nokta ve parametre adları örnektir:

# Örnek istek — gerçek adresler için ilgili API belgesine bakın
curl -H "Authorization: Bearer $API_ANAHTARI" \
  "https://api.ornek-ajans.com/v1/haberler?kategori=ekonomi&adet=2"

Sunucu isteği doğrular ve şuna benzer bir yanıt döner:

{
  "veri": [
    {
      "id": "h-102938",
      "baslik": "Merkez Bankası faiz kararını açıkladı",
      "ozet": "Para Politikası Kurulu toplantısının ardından karar duyuruldu.",
      "kategori": "ekonomi",
      "yayin_tarihi": "2026-10-24T14:05:00+03:00"
    }
  ],
  "sayfa": { "sonraki": "c2F5ZmEtMg" }
}

Yanıtın biçimi JSON'dur; JSON'un ne olduğunu ve neden bu kadar yaygın kullanıldığını JSON nedir yazımızda ayrıntılı anlattık.

HTTP Metotları

Haber sitelerinin ajans API'lerinde yaptığı işlemlerin neredeyse tamamı GET, yani okuma isteğidir.

HTTP Durum Kodları

Her yanıt, isteğin sonucunu özetleyen üç haneli bir durum koduyla gelir. Bu kodlar RFC 9110 ile tanımlanmıştır:

429 kodu RFC 6585 ile tanımlanmıştır ve istek sınırının (rate limit) aşıldığını gösterir. İyi yazılmış bir entegrasyon bu durumda hemen tekrar denemez; bekleme süresini her denemede artırarak (exponential backoff) tekrar dener.

API Türleri

"API" geniş bir kavramdır; bir yazılım kütüphanesinin fonksiyonlarından işletim sistemi çağrılarına kadar pek çok şeyi kapsar. Web dünyasında en sık karşılaşılan türler şunlardır:

• REST API: Kaynakları (haber, kategori, yazar) URL'lerle temsil eder ve HTTP metotlarıyla işlem yapar. Bugün web API'lerinin en yaygın biçimidir.
• GraphQL: İstemcinin tam olarak hangi alanları istediğini tek bir sorguda belirttiği yaklaşımdır. Gereksiz veri taşımayı azaltır.
• SOAP: XML tabanlı, sıkı kuralları olan daha eski bir yaklaşımdır. Bankacılık ve kurumsal sistemlerde hâlâ görülür. XML'in yapısı XML nedir yazısında.
• Webhook: Klasik API'de istemci sorar, sunucu cevaplar. Webhook'ta ise olay olduğunda sunucu istemciye kendiliğinden haber verir. Ayrıntısı webhook nedir yazımızda.

Erişim açısından da API'ler üçe ayrılır: herkese açık (public), yalnızca iş ortaklarına açık (partner) ve kurum içi (private). Haber ajansı API'leri genellikle partner türündedir; yalnızca abonelik sözleşmesi olan kurumlar kendilerine verilen anahtarla erişebilir.

API Anahtarı ve Kimlik Doğrulama

API anahtarı, isteği kimin gönderdiğini sunucuya kanıtlayan gizli bir dizedir. Ajans hangi abonenin hangi haberlere erişebileceğini, kaç istek yapabileceğini ve kullanım istatistiklerini bu anahtar üzerinden yönetir. Yaygın yöntemler:

• Bearer token: Authorization başlığında gönderilir.
• Özel başlık: X-API-Key gibi bir başlıkla gönderilir.
• OAuth 2.0: Kısa ömürlü erişim jetonlarının bir yetkilendirme sunucusundan alındığı daha kapsamlı yöntemdir.

Güvenlik açısından üç kural değişmez:

1. API anahtarını tarayıcıda çalışan JavaScript koduna veya mobil uygulamanın içine gömmeyin; kaynak kodu görüntüleyen herkes anahtarı alabilir. İstekleri kendi sunucunuzdan yapın.
2. Anahtarı kod deposuna yazmayın; ortam değişkeni veya gizli anahtar yöneticisi kullanın.
3. Anahtarın sızdığından şüpheleniyorsanız hemen iptal ettirip yenisini alın.

API ile RSS, FTP ve Webhook Arasındaki Fark

Haber almanın tek yolu API değildir. Yöntemlerin her birinin güçlü olduğu durumlar farklıdır:

RSS'in mantığını RSS nedir yazımızda, dosya aktarım protokollerini ise FTP ve SFTP nedir yazımızda anlattık. Hangi yöntemi seçeceğinize karar veremiyorsanız tüm seçenekleri karşılaştıran Yazar Haber Ajansı geliştirici belgeleri ana sayfası iyi bir başlangıç noktasıdır.

API Belgesi Nasıl Okunur?

İyi bir API belgesi, "menü" benzetmesindeki menünün ta kendisidir. Bir belgeyi açtığınızda sırasıyla şunlara bakın:

1. Kimlik doğrulama: Anahtarın nasıl alındığı ve isteğe nasıl ekleneceği.
2. Temel adres (base URL): Tüm uç noktaların başına eklenen kök adres ve sürüm (/v1 gibi).
3. Uç nokta listesi: Her uç noktanın metodu, parametreleri ve örnek yanıtı.
4. Sayfalama: Binlerce kaydın parçalar hâlinde nasıl alınacağı.
5. Hata biçimi: Hata yanıtının yapısı ve kodların anlamı.
6. Sınırlar: Dakikada veya günde izin verilen istek sayısı.
7. Sürüm notları: Neyin değiştiği ve eski sürümlerin ne zaman kapanacağı.

API Sürümleme Neden Önemli?

API'ler zamanla gelişir: yeni alanlar eklenir, bazı alanların adı değişir. Bu değişikliklerin mevcut entegrasyonları bozmaması için sağlayıcılar sürüm kullanır (/v1, /v2 gibi). Entegrasyonunuzu belirli bir sürüme bağlamak, sağlayıcı yeni sürüm yayınladığında sitenizin bir gecede bozulmasını önler. Sürüm notlarını takip etmek ve eski sürümün kapanış tarihinden önce geçiş yapmak, API kullanan her ekibin rutin işlerinden biri olmalıdır.

Haber Sitesi İçin API Kullanmanın Avantajları

• Hız: Ajans haberi yayınladıktan kısa süre sonra sitenizde taslak olarak hazır olur.
• Hatasız aktarım: Başlık, özet, görsel, kategori ve tarih alanları elle kopyalamadaki hatalar olmadan aktarılır.
• Tekrarı önleme: Her haberin benzersiz kimliği sayesinde aynı haber iki kez eklenmez.
• Düzeltmelerin takibi: Ajans bir haberi güncellediğinde değişiklik tarihine bakarak kendi kopyanızı da güncellersiniz.

Bir uyarıyı da eklemek gerekir: API'den gelen haberi hiçbir değer katmadan otomatik yayınlamak, aynı metnin yüzlerce sitede bulunmasına yol açar. Google, değer katmadan çok sayıda sayfa üretmeyi spam politikalarında açıkça sorunlu sayar. API'yi bir "içerik musluğu" değil, editörünüzün işini hızlandıran bir araç olarak düşünün: yerel bağlam, özgün başlık ve ek bilgiyle zenginleştirilmiş haber hem okura hem arama motoruna daha fazla değer sunar.

Yazar Haber Ajansı'nda API Nasıl Kullanılır?

Yazar Haber Ajansı'nın abone API'si, haberleri JSON olarak döndüren bir REST API'dir ve https://api.yha.com.tr/v1 kök adresinde çalışır. Bütün istekler GET'tir; anahtar Authorization: Bearer başlığıyla gönderilir. Servis edilen içerik akış ucundan imleçle (cursor) eskiden yeniye alınır; içerik türüne, kategoriye, ile ve önceliğe göre süzülebilir, düzeltme ve iptaller de ayrı olay olarak gelir. Kimlik doğrulama, uç noktalar, sayfalama, hata kodları, istek sınırları ve curl, Python, JavaScript ve C# örnekleri Yazar Haber Ajansı API belgelerinde adım adım anlatılıyor.

Geliştirme aşaması için gerçek içerik yerine yapay örnek içerik veren ayrı bir deneme ortamı (https://deneme.yha.com.tr/v1) vardır; istekler ve yanıtlar canlı ortamla aynıdır, yalnızca içerik örnektir.

Anlık bildirim istiyorsanız API'yi YHA webhook bildirimleriyle birlikte kullanabilirsiniz: webhook yeni haberi, düzeltmeyi ya da iptali sisteminize bildirir; isterseniz yalnızca kimliği alıp haberin tamamını API'den çekersiniz. API gibi otomatik çıkışlar abonelik paketine sözleşmeyle eklenir; paketleri ve teklif almayı YHA abonelik sayfasında bulabilirsiniz.

Sıkça Sorulan Sorular

API kullanmak için yazılımcı olmak gerekir mi?

API'yi kendi sisteminize bağlamak temel düzeyde programlama bilgisi ister. Ancak WordPress gibi hazır sistemlerde bu işi eklentiler üstlenir; yazılımcı olmadan da API tabanlı entegrasyon kullanabilirsiniz.

API ile web sitesi arasındaki fark nedir?

Web sitesi insanlar için tasarlanmış görsel bir arayüzdür. API ise yazılımlar için tasarlanmış, düzenli veri döndüren bir arayüzdür. Aynı haber, sitede okunabilir bir sayfa, API'de ise JSON nesnesi olarak sunulur.

API ücretli midir?

Bu, hizmeti sunan kuruma bağlıdır. Bazı API'ler ücretsiz, bazıları kullanım kotasına göre ücretlidir. Haber ajansı API'lerine erişim genellikle abonelik paketinin bir parçasıdır.

REST API ile API aynı şey mi?

Hayır. API genel kavramdır; REST, web API'lerini tasarlamanın en yaygın yöntemlerinden biridir. Her REST API bir API'dir ama her API REST değildir.

API anahtarım çalınırsa ne olur?

Başkası sizin adınıza istek yapabilir, kotanızı tüketebilir. Anahtarı hemen hizmet sağlayıcıya iptal ettirip yenisini almalısınız.