API Keşfi

WebBlocks CMS, güvenilir yapay zekâ ve operatör araçları için keşif öncelikli bir İçerik API'si sunar. Harici bir aracın mevcut uç noktaları, şemaları, örnekleri ve güvenli içerik iş akışını öğrenmesi için yalnızca CMS API temel URL'sine ve bir CMS API token'ına ihtiyacı olmalıdır.

Temel URL

/webadmin/api

Yerel yapay zekâ/operatör araçları için herkese açık site kökü yerine API temel URL'sini saklayın:

WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...

İlk istek şu olmalıdır:

GET /webadmin/api
Authorization: Bearer <token>
Accept: application/json

Kimliği Doğrulanmamış Yanıt

GET /webadmin/api bilinçli olarak herkese açık kullanıma uygundur. Geçerli bir Bearer token olmadan yalnızca asgari başlangıç JSON'ı döndürür:

  • ürün adı
  • API sürümü
  • authenticated: false
  • bir self bağlantısı
  • çağırana kimlik doğrulaması yapmasını söyleyen kısa bir mesaj

Uç nokta envanteri, site verileri, içerik sözleşmeleri, token önizlemeleri, token karmaları (hash), kullanıcı ayrıntıları, yerel yollar veya sunucu iç bilgileri döndürmemelidir.

Kimliği Doğrulanmış Yanıt

Geçerli bir CMS API Bearer token ile keşif şunları döndürür:

  • product: WebBlocks CMS
  • cms_version ve product_version
  • api_version
  • authenticated: true
  • token değeri, token önizlemesi veya token karması olmadan token yetenek adları
  • önerilen sonraki adımlar
  • OpenAPI, yapay zekâ kılavuzu, içerik sözleşmesi, örnekler, doğrulama/uygulama, sayfalar, sayfa yayınlama, sayfaya ait blok yayınlama, gezinme ve ortak slotlar için bağlantılar

Kimliği doğrulanmış yanıt, yapay zekâ/operatör araçları için kurallı başlangıç sözleşmesidir. Araçlar, CMS deposuna veya paket dokümanlarına yerel dosya sistemi erişimi varsaymak yerine döndürülen bağlantıları izlemelidir.

İçerik planlarında page.path ve expected_path, /contact veya /docs/internal-content-api gibi kurallı herkese açık sayfa çevirisi yollarıdır. /p/... yalnızca eski sürümlerle herkese açık uyumluluk içindir ve yeni araçlar tarafından üretilmemelidir.

Bağlantılı Kaynaklar

Güncel keşif bağlantıları şunları içerir:

GET /webadmin/api/openapi.json
GET /webadmin/api/ai-guide
GET /webadmin/api/content-contract
GET /webadmin/api/examples
GET /webadmin/api/examples/contact-page
POST /webadmin/api/content/validate
POST /webadmin/api/content/apply
GET /webadmin/api/pages
GET /webadmin/api/pages/{page}
POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks
GET /webadmin/api/navigation-menus
GET /webadmin/api/shared-slots

İçerik doğrulama/uygulama bağlantıları hem create_draft_page hem de replace_existing_draft_page plan modlarını destekler. Güncel mod listesi ve güvenlik kuralları için GET /webadmin/api/content-contract kullanın.

Yayınlama bağlantıları content.publish gerektirir. POST /webadmin/api/pages/{page}/publish varsayılan olarak include_page_owned_blocks: false ile yalnızca sayfa yayınlar; istek açıkça include_page_owned_blocks: true ayarlamadıkça taslak blokları yayınlamaz. Ortak slot kademeli yayınlaması desteklenmez ve JSON doğrulama geri bildirimi döndürür. POST /webadmin/api/pages/{page}/publish-page-owned-blocks, sayfa iş akışı durumunu değiştirmeden uygun sayfaya ait taslak veya incelemedeki blokları yayınlar.

GET /webadmin/api/examples/contact-page yerel bir contact_form blokunu gösterir. Araçların, operatörlerin yönetim panelinde kullandığı aynı yapılandırılmış blok sözleşmesiyle güvenli taslak iletişim sayfaları oluşturabilmesi için bilinçli olarak Trusted HTML, ham form işaretlemesi ve mailto: yedeklerinden kaçınır.

Korumalı bağlantılar şunları gerektirir:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Yetenekler

CMS API token'ları, token oluşturulurken seçilen yetenekleri keşifte gösterir; böylece araçlar yazma denemesinden önce izin verilen eylemleri anlayabilir.

Standart sayfa oluşturma yetenekleri:

  • content.read
  • content.validate
  • content.apply
  • navigation.write
  • shared-slots.write

Yıkıcı veya yayınlama yetenekleri ayrı gelişmiş seçeneklerdir ve varsayılan olarak seçili değildir:

  • content.publish
  • pages.delete

Yıkıcı işlemler açık ve eşleşen bir yetenek gerektirmelidir ve normal sayfa oluşturma token'larına verilmemelidir.

Normal sayfa oluşturma araçları yayınlamanın kullanılabilir olduğunu varsaymamalıdır. content.publish yoksa araçlar yayınlama uç noktalarını çağırmadan önce durmalı ve yayınlama yetenekli güvenilir bir operatör token'ı gerektiğini raporlamalıdır.

Yalnızca JSON Hatalar

İçerik API'si uç noktaları tarayıcı yönlendirmeleri, giriş sayfaları veya CSRF HTML yanıtları yerine JSON hataları döndürür. Hata yükleri uygun olduğunda yol gösterici bağlantılar içerir:

  • api_discovery_url
  • openapi_url
  • documentation_url
  • example_url

Beklenen durum davranışı:

  • eksik, geçersiz veya iptal edilmiş token'lar için 401
  • eksik yetenekler için 403
  • geçersiz içerik yükleri için 422

Güvenlik

Keşif, OpenAPI, yapay zekâ kılavuzu, örnekler ve içerik sözleşmesi yanıtları gerçek token değerlerini, token karmalarını, .env değerlerini, yerel dosya sistemi yollarını, sunucu yollarını, yığın izlerini (stack trace), ham istisnaları, veritabanı iç bilgilerini, kullanıcı listelerini veya özel operatör ayrıntılarını ifşa etmemelidir.

/webadmin/pages/{page}/preview gibi önizleme URL'leri tarayıcı/yönetim rotalarıdır. Kimliği doğrulanmış bir yönetici tarayıcı oturumu gerektirirler ve CMS API Bearer token'larıyla açılmazlar. Bu URL'den gelen bir giriş yönlendirmesi tarayıcı oturumunun eksik olduğu anlamına gelir; bir Dahili İçerik API'si kimlik doğrulama hatası değildir.