Bir kullanıcı yıllık satış raporu istiyor.

Rapor üretimi milyonlarca satırı okuyor ve yaklaşık 3 dakika sürüyor.

İlk implementasyon genellikle şöyle:

POST /api/reports
→ 3 dakika bekle
← 200 OK + rapor

Geliştirici ortamında çalışıyor.

Production’da ise istek 60. saniyede load balancer tarafından kesiliyor. Kullanıcı tekrar deniyor. Şimdi arka planda aynı rapordan iki tane üretiliyor.

HTTP isteği uzun işler için değil

Bir HTTP isteğinin yolunda birçok bileşen var: tarayıcı, CDN, load balancer, reverse proxy, uygulama sunucusu. Her birinin kendi timeout değeri var ve genellikle bir dakika civarında.

Uzun süre açık kalan istekler thread ve connection tutar. Deploy sırasında yarıda kesilir. Mobil bağlantılarda kopma ihtimali artar.

Birkaç saniyeyi geçmesi muhtemel işler için senkron model yerine asenkron bir model daha sağlıklı.

202 Accepted

İstek alındığında işi hemen başlatmak yerine kabul ettiğinizi söylersiniz:

POST /api/reports
{ "year": 2026 }

HTTP/1.1 202 Accepted
Location: /api/operations/71
{ "id": 71, "status": "queued" }

202 Accepted HTTP’nin tam olarak bu durum için tanımladığı status code. “İsteğini aldım, işleyeceğim, ama sonuç henüz hazır değil.”

İş bir kuyruğa konur ve arka plandaki worker’lar tarafından işlenir.

Operation kaynağı

Client işin durumunu bir kaynak üzerinden takip eder:

GET /api/operations/71

{
  "id": 71,
  "status": "running",
  "progress": 40,
  "createdAt": "2026-10-26T09:12:00Z"
}

İş bittiğinde:

{
  "id": 71,
  "status": "succeeded",
  "result": { "href": "/api/reports/2026-annual" }
}

Hata olursa, hatanın açıklamasıyla birlikte failed durumu döner.

Google’ın API tasarım rehberi bu yapıya long-running operation diyor ve birçok bulut API’si benzer bir model kullanıyor.

Polling sıklığı

Client ne sıklıkla sormalı?

Her 100 ms’de bir sormak sunucuyu gereksiz yere yorar. Her 5 dakikada bir sormak kullanıcıyı bekletir.

Sunucu bir öneri verebilir:

Retry-After: 5

Client artan aralıklarla sorgulama da yapabilir. İlk birkaç saniyede sık, sonra seyrek.

Polling’in alternatifleri de var. İş bittiğinde client’ın verdiği bir URL’ye webhook göndermek, sunucudan sunucuya entegrasyonlarda iyi çalışır. Tarayıcıda ise Server-Sent Events veya WebSocket ile durum güncellemesi göndermek, kullanıcıya canlı bir ilerleme çubuğu göstermeyi sağlar.

Ama polling her zaman bir yedek olarak kalmalı. Basittir, her client’ta çalışır ve bağlantı kopsa bile durum kaybolmaz.

Tekrarlanan istekler

Kullanıcı rapor butonuna iki kez bastı. İki ayrı iş başlamalı mı?

Bir idempotency key, aynı isteğin tekrarında yeni bir operation oluşturmak yerine mevcut olanı döndürmeyi sağlar. Bazı durumlarda iş parametrelerine göre de tekilleştirme yapılabilir. Aynı kullanıcı aynı yıl için zaten çalışan bir rapor istediyse, yeni bir iş başlatmak yerine mevcut işin adresi döndürülür.

İptal ve temizlik

Uzun süren bir işi iptal edebilmek kullanıcı için değerlidir:

POST /api/operations/71:cancel

veya

DELETE /api/operations/71

Tamamlanmış operation kayıtları ve ürettikleri sonuçlar da sonsuza kadar saklanmamalı. Belirli bir süre sonra temizlenmeleri ve bunun dokümantasyonda belirtilmesi gerekir.

Senkron API’ler basittir ve çoğu durumda doğru tercihtir.

Ama bir işin süresi kontrolünüz dışındaysa, client’ı beklemeye zorlamak yerine ona takip edebileceği bir adres vermek, hem sistem hem kullanıcı için daha dayanıklı bir sözleşmedir.