Yazılım Headless Oluyor: API'niz Artık Ürün

Özetle: Yapay zeka ajanları, kurumsal yazılımlardan kullanıcı arayüzünü sessizce kaldırıyor. API'ler ve MCP aracılığıyla açığa çıkan veri katmanı, yeni ürün yüzeyi haline geliyor. API ekiplerinin bu çeyrekte yapması gereken beş değişiklik, ayrıca henüz kimsenin çözemediği o tek sorun.

Apidog'u bugün deneyin

Kullanıcı arayüzü, eskiden B2B yazılımlarındaki en güçlü hendeklerden biriydi. Satış temsilcileri Salesforce'ta, destek ekipleri Zendesk'te, tedarik ekipleri SAP'de çalışıyordu. Erişim sıklığı, kas hafızası ve formlar üzerinden zorlanan veri hijyeni, ürünü yapışkan hale getiriyordu. Veri ise bu sürecin arkasında depolanan katmandı.

Bu dönem kapanıyor. Yapay zeka ajanları artık tarayıcı açmadan, API'ler üzerinden kurumsal verileri doğrudan okuyup yazabiliyor. Salesforce, veri katmanını ajanlara açan başsız bir ürününü şimdiden duyurdu. Diğer kayıt sistemleri de yıllar değil, haftalar geriden geliyor.

Sonuç: Kullanıcı arayüzü artık tek hendek değilse, API hendektir. Bu da API'nin nasıl tasarlanması, belgelenmesi, test edilmesi ve yetkilendirilmesi gerektiğini değiştirir.

Uygulamada “başsız yazılım” ne anlama geliyor?

Başsız yazılım, ajanların doğrudan okuyup yazabilmesi için veri katmanını API'ler aracılığıyla açığa çıkaran kurumsal yazılımdır. Kullanıcı arayüzü ortadan kalkmaz; yalnızca tek giriş noktası olmaktan çıkar.

Bu kavram, “API-öncelikli” veya “başsız CMS” ile aynı şey değildir:

• API-öncelikli: yazılımı tasarlama metodolojisidir.
• Başsız CMS: içerik mimarisidir.
• Başsız yazılım: tüketicinin değiştiğini söyler. Artık veriyi okuyan/yazan taraf tarayıcıdaki bir insan değil, MCP erişimi ve hedefi olan bir ajandır.

Bunu aynı anda üç gelişme mümkün kıldı:

1. Araçları planlayıp seçebilen LLM'ler.
2. Ajanların harici sistemleri keşfetmesini standartlaştıran MCP.
3. Veri çıkarmanın ucuzlaması; yani API'yi kapalı tutmanın alttaki veriyi korumaya yetmemesi.

Eğer API'niz, “bir geliştirici istemci yazar, sonra insanlar o istemciyi kullanır” varsayımıyla tasarlandıysa, ajanlar için yeniden düşünmeniz gerekir.

Artık geçerli olmayan beş bağlılık faktörü

Kurumsal sistemleri uzun süre yapışkan tutan beş faktör vardı. Ajanların dünyasında bunların çoğu zayıflıyor.

1. Erişim sıklığı

Kullanıcılar aynı arayüzü her gün kullandıkça kas hafızası oluşur. Satış temsilcileri yıllarca günde sekiz kez Salesforce'a giriş yapıyordu.

Ajanların kas hafızası yoktur. Araç değiştirme maliyeti çoğu zaman bir yapılandırma dosyasını değiştirmek kadardır.

2. Okuma-yazma iş akışları

Sürekli veri hareketi, geçişleri riskli hale getiriyordu. Ajanlar ise makine hızında okur ve yazar. Sözleşme stabil olduğu sürece API'nin arkasındaki veritabanının ne olduğu onlar için ikincildir.

3. Belgelenmemiş SOP'lar

“100.000 dolardan fazla anlaşmalar Başkan Yardımcısı onayı gerektirir” gibi kurallar çoğu zaman kodda, belgede veya üründe açık değildir.

Ajanlar için bu hâlâ zordur. Ancak ajanlar iş akışını yürüttükçe bu kurallar okunabilir ve test edilebilir politikalara taşınmak zorunda kalır.

4. Dahili alışkanlık döngüleri

Bir ekibin günlük toplantısı, raporları ve ritüelleri belirli bir araç etrafında şekillenmiş olabilir. Ancak günlük işler ajanlar üzerinden akmaya başladığında bu alışkanlık döngüsü çözülür.

5. Uyumluluk kritikliği

Ayakta kalan ana faktör budur. Yasal risk, veriyi insanın mı ajanın mı taşıdığına bakmaz. Denetim izi, yetkilendirme ve geri alınabilirlik hâlâ gerekir.

Beş hendekten dördü zayıflıyor. Beşincisi, yeni savunulabilirliğin oluşacağı yerdir.

API ekiplerinin bu çeyrekte değiştirmesi gereken beş şey

API yeni ürün yüzeyi ise, API ekiplerinin önceliği sadece endpoint eklemek olmamalı. Sözleşme, keşfedilebilirlik, niyet, yetki ve denetim aynı anda ele alınmalı.

1. API'nizi boru hattı olarak değil, ürün yüzeyi olarak ele alın

“Ön uç çağırabilsin” diye tasarlanmış bir REST endpoint'i ile ajanın düşünüp seçerek çağırdığı endpoint aynı şey değildir.

İlkinde şunlar tolere edilebilir:

• Tutarsız adlandırmalar
• Eksik dokümantasyon
• UI'a özel alanlar
• Belirsiz hata mesajları
• Aynı alanın bağlama göre farklı anlamlara gelmesi

Ajan odaklı API'de bunlar sorun çıkarır. Çünkü ajan, endpoint'in davranışını sözleşmeden anlamak zorundadır.

Eğer yapay zeka ajanları için API tasarlıyorsanız, sözleşme arayüzün kendisidir.

Kötü hata yanıtı:

{
  "error": "Bad Request"
}

Daha kullanışlı hata yanıtı:

{
  "error": {
    "code": "missing_required_field",
    "message": "Gerekli customer_id alanı eksik.",
    "hint": "Bu faturanın ait olduğu müşterinin kimliğini customer_id alanında iletin."
  }
}

Basit turnusol testi:

Yetkin bir ajan, yalnızca OpenAPI spesifikasyonu ve alan açıklamaları ile API'nizi doğru çağırabilir mi?

Eğer yanıt “hayır, eski kullanıcı arayüzünün kaynak koduna da bakması gerekir” ise API hâlâ ürün yüzeyi değil, boru hattıdır.

2. MCP'yi REST ve GraphQL ile birlikte sunun

REST, ajanların API'nizin var olduğunu öğrendikten sonra onu çağırma yoludur. MCP ise başlangıçta neler yapabileceğini keşfetme yoludur.

MCP sunucusu olmayan bir REST API, robots.txt ve site haritası olmayan bir web sitesi gibidir. Teknik olarak çağrılabilir ama onu bulmak ve doğru kullanmak zordur.

Bu, mevcut API'nizi atmanız gerektiği anlamına gelmez:

• REST'i koruyun.
• GraphQL varsa koruyun.
• Aynı yetenekleri ajanların konuştuğu protokol üzerinden açığa çıkarmak için MCP ekleyin.

Anthropic MCP spesifikasyonu sözleşme tarafını kapsar. Apidog ise test, belgeleme ve doğrulama tarafında kullanılabilir.

MCP'yi API ekipleri açısından daha detaylı anlamak için bu derinlemesine incelemeye bakabilirsiniz.

Pratik kontrol listesi:

[ ] MCP sunucusu mevcut mu?
[ ] Araç adları açık ve eylem odaklı mı?
[ ] Her aracın giriş/çıkış şeması belgeli mi?
[ ] Hata yanıtları ajan tarafından yorumlanabilir mi?
[ ] MCP araçları mevcut REST/GraphQL yetenekleriyle tutarlı mı?

3. Şemaları CRUD nesneleri etrafında değil, niyetler ve sonuçlar etrafında tasarlayın

Salesforce veri modelinde Fırsatlar, Potansiyel Müşteriler, Hesaplar ve Kişiler vardır. Ajanlar ise genellikle bu nesnelerle düşünmez. Hedeflerle düşünür:

• “Ayrılmak üzere olan hesapları bul.”
• “Dün kapanan anlaşma için teklif taslağı oluştur.”
• “Gece P0 bileti açan hesabı yükselt.”

Yeni nesil kayıt sistemleri yalnızca CRUD nesneleri etrafında değil; görevler, niyetler, iş akışları, politikalar ve sonuçlar etrafında şekillenecek.

Bu, mevcut şemanızı bir gecede yeniden yazmanız gerektiği anlamına gelmez. Üzerine niyet odaklı bir katman ekleyebilirsiniz.

Örneğin ajanı şu üç ayrı işlemi yapmaya zorlamak yerine:

POST /opportunities
POST /activities
POST /tasks

Şuna benzer bir endpoint sunabilirsiniz:

POST /intents/capture-buying-signal

Örnek istek:

{
  "account_id": "acc_123",
  "signal": "Müşteri satın almaya hazır olduğunu belirtti.",
  "source": "sales_call_transcript",
  "owner_id": "user_456"
}

Örnek yanıt:

{
  "created": {
    "opportunity_id": "opp_789",
    "activity_id": "act_234",
    "task_id": "task_567"
  },
  "next_recommended_action": "Teklif taslağı oluştur."
}

Burada niyet API haline gelir; CRUD ise uygulama detayı olur.

Bu geçiş için daha fazla desen görmek isterseniz API'nizi yapay zeka ajanlarına hazır hale getirme rehberine bakabilirsiniz.

4. Ajan kimliğini ve kapsamlı izinleri çözün

Bu, henüz tam çözülmemiş en kritik konulardan biri. Her ajan çağrısının şunları ayırt edebilmesi gerekir:

• Hangi kullanıcı adına hareket ediyor?
• Hangi ajan hareket ediyor?
• Hangi izin kapsamıyla hareket ediyor?
• Eylem insan tarafından mı, ajan tarafından mı tetiklendi?
• Bu eylem daha sonra denetlenebilir mi?

Eğer API'niz şu iki durumu ayırt edemiyorsa risk vardır:

Alice düğmeye tıkladı.
Alice'in ajanı, Alice uyurken sabah 03:00'te onun adına düğmeye tıkladı.

Minimum uygulanabilir yaklaşım:

X-Acting-On-Behalf-Of: user_123
X-Agent-Identity: renewal-agent@1.4.2
X-Agent-Run-Id: run_987

Ayrıca ajan token'larını kullanıcı token'larından ayırın. Kullanıcının mevcut oturum token'ını ajan için yeniden kullanmayın.

Güncel desenler için MCP güvenlik politikalarına bakabilirsiniz.

5. Eylem katmanını denetim izi ve kapalı döngü geri bildirimle oluşturun

Yeni savunulabilirlik sadece kaydı depolamakta değildir. Savunulabilirlik şu döngüde oluşur:

1. Eylemi gerçekleştir.
2. Sonucu gözlemle.
3. Denetim izini kaydet.
4. Geri bildirimi gelecekteki kararları iyileştirmek için kullan.

CRM verilerinizi tutan bir SaaS ürünü, kullanıcı arayüzü olan bir veritabanıdır. Sizin adınıza eylem gerçekleştiren, sonucu gözlemleyen ve zamanla daha iyi karar veren bir SaaS ürünü ise farklı bir kategoridir.

API tarafında üç gereksinim ortaya çıkar:

• Eylem endpoint'leri sonuç callback'i veya webhook desteklemeli.
• Her eylem tekrar oynatılabilir olmalı.
• Her eylem için girişler, çıkışlar, ajan kimliği ve mümkünse akıl yürütme izi kaydedilmeli.

Örnek denetim kaydı:

{
  "audit_id": "audit_001",
  "actor_type": "agent",
  "agent_identity": "renewal-agent@1.4.2",
  "acting_on_behalf_of": "user_123",
  "action": "create_discount_offer",
  "input": {
    "account_id": "acc_123",
    "discount_percent": 10
  },
  "output": {
    "offer_id": "offer_456",
    "status": "created"
  },
  "policy_version": "2026-05-01",
  "timestamp": "2026-05-26T10:15:00Z"
}

Veri kaybetmeden ajan iş akışlarını test etmek, bu değişimin operasyonel tarafını ele alır.

Çözülmemiş kısım: ajan yetkilendirmesi

Ajanlara hazır yazılımlardaki en önemli boşluk yetkilendirmedir:

Hangi ajan, kimin adına, hangi denetlenebilirlik ile ne yapabilir?

2026'daki dürüst yanıt: Neredeyse kimse bunu tamamen iyi çözmüş değil.

Mevcut araçların sınırları var:

• OAuth, yetkilendirilmiş kullanıcı erişimi için tasarlandı; ajanlar için değil.
• RBAC, insan rolleri için tasarlandı.
• Denetim günlükleri, kullanıcıların ne yaptığını izlemek için tasarlandı; hangi kullanıcının ajanının hangi politika altında ne yaptığını izlemek için değil.

Standartlar tam oturmadan da bugün uygulanabilecek dört model var.

1. Ajan kimliği başına kapsamlı token kullanın

Bir kullanıcının oturum token'ını, onun adına hareket eden ajan için yeniden kullanmayın.

Bunun yerine:

• Ayrı token düzenleyin.
• Daha dar kapsam verin.
• Bağımsız olarak döndürün.
• Sızıntı durumunda kullanıcıyı değil, ajanı iptal edin.

Örnek kapsam:

agent:read_accounts
agent:create_tasks
agent:refunds:max_50_usd

2. Her istekte delegasyon meta verisi taşıyın

Her API çağrısı, en azından şu bilgileri taşımalıdır:

X-Acting-On-Behalf-Of: user_123
X-Agent-Identity: support-agent@2.1.0
X-Agent-Run-Id: run_abc123

Bu, endpoint mantığınızı tamamen değiştirmeden denetim hikayenizi ciddi şekilde iyileştirir.

3. Ajan eylemleri için sadece eklemeye açık denetim günlükleri oluşturun

Ajan eylemlerini kullanıcı eylemleriyle aynı tabloya gömmek yerine ayrı bir denetim tablosunda tutun.

Uyumluluk ekipleri şu soruya hızlı yanıt arayacaktır:

Bu hafta ajanlar hangi müşteri kayıtlarını değiştirdi?

Bu sorgu, insan kullanıcı aktiviteleri arasında kaybolmamalıdır.

4. Politikayı kod olarak yönetin

Her ajan sınıfının ne yapabileceğini sürüm kontrollü bir yapılandırma dosyasında belirtin.

Örnek:

agents:
  support-agent:
    version: "2.1.0"
    allowed_actions:
      - read_account
      - read_invoice
      - issue_refund
    constraints:
      max_refund_usd: 50
      can_delete_accounts: false

  renewal-agent:
    version: "1.4.2"
    allowed_actions:
      - read_account
      - create_discount_offer
      - create_task
    constraints:
      max_discount_percent: 15
      requires_human_approval_above_percent: 10

Bunu inceleyin, test edin ve değişikliklerini pull request üzerinden yönetin. İzin politikası bir wiki sayfası değil, derleme yapıtı olmalıdır.

Bunların hiçbiri tamamlanmış bir standart değildir. Ama hepsi bugün gönderilebilir.

Apidog nerede devreye giriyor?

API'nizi ürün olarak ele alacaksanız tasarım, sözleşme, mocking, MCP, test ve denetimi tek yerde yönetebileceğiniz bir çalışma alanına ihtiyacınız var. Apidog bu iş akışı için tasarlandı ve yukarıdaki beş değişiklikle doğrudan örtüşüyor.

• Değişim 1 — API'yi ürün olarak ele alma: Şema-öncelikli tasarım ve otomatik dokümantasyon ile sözleşmeyi ajanların okuyacağı tek doğruluk kaynağı haline getirebilirsiniz.
• Değişim 2 — REST ile birlikte MCP: Göndermeden önce MCP sunucunuzu doğrulamak için özel MCP sunucu test araçlarını kullanabilirsiniz.
• Değişim 3 — Niyet odaklı API'ler: Dinamik yanıtlarla mocking yaparak arka uç hazır olmadan niyet endpoint'lerini prototipleyebilirsiniz.
• Değişim 4 — Yetkilendirme: Ortam yönetimi ile ajan token'larını kullanıcı token'larından ayırabilir, iddia testleriyle politika uygulamasını doğrulayabilirsiniz.
• Değişim 5 — Eylem katmanı ve denetim: Nisan ayında çıkan Yapay Zeka Ajan Hata Ayıklayıcı ve A2A Hata Ayıklayıcı, ajan odaklı API çağrılarını uçtan uca izlemenizi, tekrar oynatmanızı ve üzerinde iddialar çalıştırmanızı sağlar.

Henüz denemediyseniz, Apidog'u indirin ve mevcut OpenAPI spesifikasyonunuzu içe aktarın. Sadece mock sunucu bile çoğu ekip için ilk geçiş maliyetini karşılar.

İddia

API ekiplerinin şu anda yapması gereken iddia basit:

API'nin kendisi üründür.

Eğer API yalnızca ön uca veri taşıyan bir boru hattıysa, metalaşır. Eğer ajanların üzerinde düşündüğü, seçtiği, güvendiği ve eylem aldığı yüzeyse, hendek haline gelir.

Bu çeyrekte ürün çıkaran ekipler, beş yıl önce tasarlanmış API yüzeylerinden çok farklı sözleşmelerle çalışacak. Bekleyen ekipler ise 2027'de, büyük bir müşteri ajan entegrasyonunun neden “doğru çalışmadığını” sorduktan sonra, aynı işi son teslim tarihi baskısı altında yapmak zorunda kalacak.