Biz bir haber sitesi değiliz

Geliştirici Dokümantasyonu

HaberAPI, yayın ekipleri için operasyon motorudur. Bu sayfa; kaynak toplama, normalize etme, SEO enrich ve API/Webhook dağıtımının teknik olarak nasıl kurulduğunu gösteren ana geliştirici girişidir.

Proof Blokları

Metrikler canlı probe ve veritabanı agregasyonundan üretilir. Son doğrulama: 09.04.2026 05:11:47.

Outage

Uptime Status

Outage

Kaynak: http://api:8080/v1/healthz + http://api:8080/v1/status

p95 hedef < 120ms

Latency (Live Probe)

2063ms

Kaynak: http://api:8080/v1/healthz (live probe)

Son 24 saat

Günlük İçerik Akışı

N/A

Kaynak: PostgreSQL public.articles

Not: Flow metric could not be computed

İki Ayrı Başlangıç Hattı

Ürünü değerlendiren ekipler için karar akışını iki lane olarak netleştiriyoruz: Developer lane ve Enterprise lane.

Developer Lane

Portal kaydını aç ve ücretsiz paket ile API key üret
Quickstart ile ilk istek + response doğrulaması yap
SDK ve webhook ile üretim hattına geç

Ücretsiz Başla Demo Akışı

Enterprise Lane

Trafik, SLA ve güvenlik gereksinimlerini netleştir
Tenant governance ve onboarding planını çıkar
Özel kontrat + geçiş planı ile canlıya al

Satış ile Planla Planları Karşılaştır

How It Works

HaberAPI bir haber sitesi değil, yayıncı operasyon motorudur. Akış her tenant için aynı standartla çalışır.

Adım 1

Kaynaklar

Adım 2

Normalize

Adım 3

SEO Enrich

Adım 4

API / Webhook

Hızlı Başlangıç

API'yi ilk kez kullanmaya başlayın

Kimlik Doğrulama

X-API-Key ile güvenli erişim

Hata Kodları

Standart hata formatları ve çözümleri

Webhooks

Olay tabanlı bildirimler

Rate Limits & Kota

Kullanım limitleri ve header'lar

OpenAPI Spec

Public tenant API sözleşmesi (JSON)

Hızlı Başlangıç

İnteraktif API Playground

Sekmeli örnek istek + tek tık kopyala + canlı response preview.

curl -s "https://haberapi.com.tr/v1/status" \
  -H "Accept: application/json"

Live Response Preview

{}

1. API Anahtarı Alın

API'yi kullanmak için önce portal kaydı açıp ücretsiz paket ile API anahtarı oluşturun.Kayıt ol ve ilk key'i oluşturarak devam edin.

2. İlk İsteğinizi Yapın

curl -X GET "https://haberapi.com.tr/v1/articles?limit=5" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

3. SDK Kurulumu (Opsiyonel)

TypeScript / JavaScript

npm install haber-sdk-ts

Python

pip install haber-sdk

Kimlik Doğrulama

İçerik ve veri endpointleri için X-API-Key, portal endpointleri için Authorization: Bearer kullanılır.

# Her istekte API anahtarınızı gönderin
X-API-Key: hk_live_xxxxxxxxxxxxxxxxxxxxx

# Portal endpointleri için JWT
Authorization: Bearer eyJhbGciOi...

Güvenlik: API anahtarını client-side bundle içine koymayın. İstekleri her zaman backend servisiniz üzerinden yönetin.

API Referansı

Public tenant sözleşmesi canlı olarak /v1/openapi.json üzerinden yayınlanır. Internal/admin operasyonları ayrı internal sözleşmede tutulur.

Canlı OpenAPI özeti şu anda yüklenemedi. JSON sözleşmesini doğrudan aşağıdaki bağlantıdan açabilirsiniz.

OpenAPI JSON Aç Changelog Gör

Endpoint Coverage

Landing üzerinde öne çıkan ürün alanları ve canlı endpoint grupları aşağıdadır.

Grup	Auth	Örnek Endpointler
Articles	X-API-Key	`GET /v1/articles` `GET /v1/articles/{id}`
Radar	X-API-Key	`GET /v1/radar/trends` `GET /v1/radar/black-swans`
Search & Analytics	X-API-Key	`GET/POST /v1/search` `GET /v1/search/articles` `GET /v1/search/stories` `GET /v1/analytics/trends`
Portal	Bearer JWT	`GET/POST /v1/portal/webhooks` `PATCH/DELETE /v1/portal/webhooks/{id}` `GET /v1/portal/saved-searches`
Operational	X-API-Key veya Bearer JWT	`GET /v1/quota/status` `GET /v1/rate-limit/status` `GET /v1/portal/status/quota` `GET /v1/portal/status/rate-limit`

Search Endpointleri

Arama için üç farklı yüzey sunulur. Kullanım senaryonuza göre doğru endpointi seçmeniz entegrasyon hızını ve sonuç kalitesini artırır.

Endpoint	Ne Zaman Kullanılır?	Özet
`GET /v1/search`	Basit query string ile hızlı arama gerektiğinde.	Tek satır sorgu, hızlı prototipleme ve dashboard filtreleri için idealdir.
`POST /v1/search`	Çoklu filtre, sıralama ve semantic/hybrid arama gerektiğinde.	DSL payload ile gelişmiş sorgu akışı kurar; üretim segmentasyonu için önerilir.
`GET /v1/search/articles`	Articles odaklı daha açık path yapısı tercih edildiğinde.	Arama sonucu doğrudan article listesi olarak döner; legacy/path-based entegrasyonlarla uyumludur.

1) GET /v1/search - Search Articles

Query string üzerinden hızlı arama yapar. En temel kullanımda q ve limit parametreleri yeterlidir.

curl -G "https://haberapi.com.tr/v1/search" \
  --data-urlencode "q=ekonomi" \
  --data-urlencode "limit=5" \
  --data-urlencode "cursor=" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

2) POST /v1/search - Search Articles (DSL)

Filtre ve ranking ihtiyacı arttığında DSL kullanın. Bu yöntem özellikle tenant bazlı üretim kurallarında daha kontrollü sonuç verir.

Not: Bu endpointte desteklenen ana alanlar query.must,query.should, filters,size, cursor vesemantic'tir.

curl -X POST "https://haberapi.com.tr/v1/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "query": {
      "must": ["deprem hazırlık"],
      "should": ["risk azaltma"]
    },
    "filters": {
      "categories": ["Gündem"],
      "tags": ["afet"]
    },
    "size": 10,
    "semantic": false
  }'

3) GET /v1/search/articles - Detailed Path

Path ayrımıyla articles aramasını açıkça ifade etmek isteyen ekipler için uygundur. Özellikle route-level izleme ve cache kuralı ayrımında tercih edilir.

curl -G "https://haberapi.com.tr/v1/search/articles" \
  --data-urlencode "q=teknoloji" \
  --data-urlencode "limit=10" \
  --data-urlencode "sort=published_at:desc" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Takedown / Tombstone

Kaldırılan içeriklerde 404 yerine200 + tombstone döner. Client tarafında tombstone=true geldiğinde içerik render etmeyin verequest_ref değerini audit kaydına alın.

{
  "tombstone": true,
  "resource": "article",
  "id": "uuid-or-string",
  "status": "removed",
  "reason_code": "COPYRIGHT_DMCA",
  "reason_public": "Bu içerik telif nedeniyle kaldırılmıştır.",
  "removed_at": "2026-02-19T10:00:00Z",
  "expires_at": null,
  "appeal_url": "https://haberapi.com.tr/docs/takedown",
  "request_ref": "TD-2026-000123",
  "meta": {
    "policy_version": "2026-01",
    "jurisdiction": "OTHER",
    "source": "internal_review"
  }
}

reason_code enum:

COPYRIGHT_DMCA, COPYRIGHT_LOCAL, LEGAL, PRIVACY, POLICY, CUSTOMER_REQUEST, OTHER

Hata Kodları

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "request_id": "req_abc123"
  }
}

HTTP Kodu	Hata Kodu	Açıklama
400	BAD_REQUEST	Geçersiz istek parametreleri
401	UNAUTHORIZED	Geçersiz veya eksik API anahtarı
403	FORBIDDEN	Erişim yetkisi yok
429	RATE_LIMITED	Rate limit aşıldı
500	INTERNAL_ERROR	Sunucu hatası

Rate Limits & Kota

Her yanıtta limit ve kota bilgileri header olarak döner:

Header	Açıklama
X-RateLimit-Limit	Dakika başına maksimum istek
X-RateLimit-Remaining	Mevcut pencere için kalan istek
Retry-After	429 sonrası tekrar deneme süresi (saniye)
X-Quota-Limit	Aylık toplam kota
X-Quota-Remaining	Kalan aylık istek hakkı

Webhooks

Webhook'lar, önemli olaylar gerçekleştiğinde belirlediğiniz URL'ye HTTP POST gönderir.

quota.exceeded aylık kota dolduğunda
saved_search.match saved-search eşleşmesi bulunduğunda
article.enriched makale enrichment süreci tamamlandığında
radar.* radar trend/black-swan eventleri oluştuğunda
webhook.test portal test webhook tetiklendiğinde

İmza Doğrulama

import crypto from 'crypto';

function verifySignature(
  timestamp: string,
  payload: string,
  signature: string,
  secret: string
) {
  const signed = `${timestamp}.${payload}`;
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Production Checklist

API anahtarı sadece backend ortamında tutuluyor.
429 ve 5xx yanıtlarında exponential backoff retry uygulanıyor.
X-Request-Id loglara kaydediliyor.
Webhook signature doğrulaması ve replay koruması aktif.
Anahtar rotasyonu için düzenli operasyon planı tanımlı.

Sık Sorulan Sorular

Admin endpointleri neden public spec'te yok?

Public sözleşme yalnızca tenant-facing API'yi kapsar. Internal/admin operasyonları ayrı, yetki korumalı sözleşmede tutulur.

SDK kullanmak zorunlu mu?

Hayır. REST API'yi doğrudan kullanabilirsiniz. SDK'lar sadece hata yönetimi ve entegrasyon hızını iyileştirmek için önerilir.

Entegrasyon desteği alabilir miyiz?

Evet. Kurumsal entegrasyon ve onboarding içiniletişim ekibine ulaşabilirsiniz.

Endpoint

Hızlı query-string araması için temel endpoint.

Request Example

curl --request GET \
  --url "https://haberapi.com.tr/v1/search?q=ekonomi&limit=5" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Accept: application/json"

Response Body

N/A

{
  "message": "İstek çalıştırıldığında canlı yanıt burada görünür."
}

Operasyonel Özet

OpenAPI vunknown ve 0 aktif endpoint.

Status Sayfasını Aç