Dahili İçerik API'si

Amaç

Dahili İçerik API'si, güvenilen yapay zekâ ve operatör araçları için güvenli bir CMS API'sidir. Bu araçların; tarayıcı yönetici arayüzüne giriş yapmadan, sayfaları kazımadan veya tarayıcıyı otomatikleştirmeden, yapılandırılmış JSON üzerinden CMS içerik sözleşmelerini incelemesine, önce-taslak içerik oluşturmasına, mevcut taslak sayfalardaki sayfaya ait belirli slotları değiştirmesine ve açık yayınlama işlemleri çalıştırmasına olanak tanır.

Faz 1; salt okunur içerik keşfi ve doğrulanmış içerik planları üzerinden taslak sayfa oluşturma için token korumalı, yalnızca JSON döndüren, herkese açık olmayan bir API olarak uygulanmıştır. Faz 2A; gezinme menüleri, Ortak Slotlar ve sayfa slotlarına açık Ortak Slot ataması için güvenli temeller ekler. Faz 2B, mevcut sayfalardaki sayfaya ait slot içeriği için kontrollü, yalnızca taslakta geçerli değiştirme ekler. Yayınlama uç noktaları açıktır ve content.publish gerektirir; içerik uygulama önce-taslak kalır ve yayınlamaz. API bilinçli olarak dar kalır: uzak veri çekme yok, içerik uygulama üzerinden geniş çaplı sayfa silme yok, Ortak Slot destekli slotların değiştirilmesi yok ve Ortak Slot kademeli yayınlama yok.

Ürün Konumlandırması

Dahili İçerik API'si:

dahili/operatör CMS API'sidir
token korumalıdır
herkese açık değildir
headless CMS teslim API'si değildir
yönetici izinlerinin yerine geçmez
içe/dışa aktarmanın yerine geçmez
bir yapay zekâ sağlayıcı entegrasyonu değildir

Bu API'nin sahibi CMS çekirdeği olmalıdır; çünkü API, çekirdek içerik kavramları üzerinde çalışır: siteler, sayfalar, yerleşimler, slotlar, bloklar, çeviriler, gezinme ve ortak slotlar. Yapay zekâ veya operatör araçları API'yi çağırabilir, ancak CMS çekirdeği OpenAI, LLM, tarayıcı (crawler) veya sağlayıcıya özgü entegrasyon mantığı barındırmamalıdır.

Rota Öneki

Kanonik önek şudur:

/webadmin/api

Bu, kısa ve tanıdık bir API segmenti kullanırken API'yi CMS yönetici sınırının içinde tutar. Kaynak tarzı uç noktalar, /webadmin/api/pages ve /webadmin/api/blocks gibi doğrudan bu önekin altında yer almalıdır.

API keşfi şuradan başlar:

GET /webadmin/api

Kimliği doğrulanmamış çağıranlar yalnızca herkese açık ve güvenli önyükleme JSON'u alır. Kimliği doğrulanmış çağıranlar güvenli ürün sürümü meta verilerini ve OpenAPI, yapay zekâ rehberi, içerik sözleşmesi, örnekler, içerik doğrulama/uygulama, sayfalar, gezinme ve Ortak Slotlar bağlantılarını alır. Harici yapay zekâ/operatör araçları, CMS deposunu veya yerel paket dokümanlarını okumak yerine bu canlı keşif yanıtından başlamalıdır.

Plan tabanlı içerik işlemleri şunu kullanır:

POST /webadmin/api/content/validate
POST /webadmin/api/content/apply

Kaçınılması gereken rota seçimleri:

/webadmin/internal-api, çünkü gereksiz yere uzundur
/webadmin/api/content-plans/..., çünkü content-plans URL sözleşmesi için fazla teknik ve dardır
her kaynağı /webadmin/api/content/... altına yerleştirmek, çünkü kaynak API'leri açık ve doğrudan kalmalıdır
/admin, çünkü CMS, ana ürünün /admin yolunun CMS'ye ait olduğunu varsaymamalıdır
/cms, çünkü /cms yalnızca statik CMS varlıkları için ayrılmıştır

Kimlik Doğrulama

API, Bearer token kimlik doğrulaması kullanır:

Authorization: Bearer <token>

CMS API token'ları, bir CMS süper yöneticisi tarafından System -> API Tokens üzerinden oluşturulur. CMS, cms_api_tokens veritabanı tablosunda yalnızca bir SHA-256 karması ve güvenli bir önizleme saklar. Düz metin token, oluşturmadan hemen sonra yalnızca bir kez gösterilir ve bir daha asla gösterilmez.

Süper yöneticiler, denetim satırını görünür tutarak API erişimini anında devre dışı bırakmak için bir token'ı iptal edebilir veya token kaydını listeden kalıcı olarak kaldırmak için silebilir. Etkin bir token'ı silmek de API erişimini anında devre dışı bırakır; çünkü kimlik doğrulayıcı artık eşleşen saklı bir karma bulamaz.

Yerel yapay zekâ ve operatör araçları, üretilen token'ı güvenilen bir operatör gizli anahtar deposunda saklamalıdır.

Yerel operatör yapılandırmasında Dahili İçerik API'si temel URL'sini kullanın:

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

CMS çalışma zamanı WEBBLOCKS_CMS_INTERNAL_API_TOKEN gerektirmez.

Kimlik doğrulama kuralları:

eksik, yanlış veya iptal edilmiş token'lar JSON 401 döndürür
iptal edilen token'lar anında çalışmayı durdurur
token'lar günlüklere, tanılamalara, destek raporlarına, testlere veya dokümantasyon örneklerine asla yazdırılmamalıdır
token karşılaştırması sabit zamanlı karşılaştırma kullanmalıdır
başarılı API istekleri token'ın last_used_at ve last_used_ip değerlerini günceller
başarılı API istekleri, operatör denetim bağlamı için kısaltılmış bir user-agent da saklar
yanıtlar yalnızca JSON'dur

Örnek istek:

GET /webadmin/api/sites
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Yetenekler

Süper yöneticiler, System -> API Tokens üzerinden token oluştururken token yeteneklerini seçer ve daha sonra token gizli değerini açığa çıkarmadan veya döndürmeden token'ın adını ve yeteneklerini düzenleyebilir. Keşif; token değerini, token karmasını veya token önizlemesini döndürmeden kayıtlı yetenekleri gösterir. Standart sayfa oluşturma token'ları varsayılan olarak şu yeteneklere sahiptir:

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

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

content.publish
pages.delete

Yazma uç noktaları ilgili yeteneği sunucu tarafında denetler. Eksik yetenekler; api_discovery_url, openapi_url, documentation_url ve example_url yönlendirmesiyle birlikte JSON 403 döndürür. Normal sayfa oluşturma token'ları yıkıcı yetenekler içermemelidir.

API Modeli

API'nin birbirini tamamlayan iki modu vardır.

Kaynak API'si

Kaynak uç noktaları, yönetici eşdeğeri tekil işlemleri yansıtır:

sayfaları listeleme ve okuma
blokları listeleme ve okuma
siteleri, dilleri (locale), yerleşimleri ve blok türlerini listeleme
daha sonra taslak sayfa kaynaklarını doğrudan oluşturma veya güncelleme
daha sonra sayfa slotlarını listeleme veya sağlama
daha sonra kaynak uç noktaları üzerinden blok ekleme, güncelleme, taşıma ve silme
daha sonra kaynak uç noktaları üzerinden alt blok ekleme
daha sonra gezinme ve ortak slotları yönetme

Faz 1 kaynak uç noktaları:

GET /webadmin/api/sites
GET /webadmin/api/locales
GET /webadmin/api/page-layouts
GET /webadmin/api/block-types
GET /webadmin/api/content-contract
GET /webadmin/api/pages
GET /webadmin/api/pages/{page}
POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks
POST /webadmin/api/pages/{page}/slots/{slot}/shared-slot
GET /webadmin/api/blocks
GET /webadmin/api/blocks/{block}
GET /webadmin/api/navigation-menus
GET /webadmin/api/navigation-menus/{navigationMenu}
POST /webadmin/api/navigation-menus
POST /webadmin/api/navigation-menus/{navigationMenu}/items
GET /webadmin/api/shared-slots
GET /webadmin/api/shared-slots/{sharedSlot}
POST /webadmin/api/shared-slots
POST /webadmin/api/shared-slots/{sharedSlot}/blocks

İçerik Doğrulama / Uygulama API'si

İçerik doğrulama/uygulama uç noktaları, çok adımlı eksiksiz içerik planlarını işler:

POST /webadmin/api/content/validate
POST /webadmin/api/content/apply

validate, eksiksiz bir içerik planını denetler ve hiçbir şey yazmaz. apply, planı yeniden doğrular ve ardından istenen taslak sayfayı, gezinme öğelerini, Ortak Slotları, Ortak Slot blok ağaçlarını ve sayfa slotu Ortak Slot atamalarını tek bir işlem (transaction) içinde oluşturur. Plan mode: replace_existing_draft_page kullandığında ve iyimser bir güvenlik koruması içerdiğinde, mevcut bir taslak sayfadaki adlandırılmış sayfaya ait slotları da değiştirebilir. Bu; CMS'nin yarım oluşturulmuş içerikten kaçınması gereken yapay zekâ üretimi sayfalar, şablonlar, başlangıç sayfaları, ortak üst bilgiler/alt bilgiler ve taşıma yardımcıları için kullanışlıdır.

İstek gövdesi yine bir plan alanı veya başka bir yapılandırılmış içerik planı yükü içerebilir. URL, /content/validate ve /content/apply olarak kalmalıdır.

Her iki mod da gereklidir:

Kaynak API'si, mevcut CMS içerik modelini ve sözleşmelerini dahili araçlara açar
İçerik Doğrulama / Uygulama API'si, daha büyük sayfa oluşturma işlemlerinde kısmi yazmaları önler

Mevcut Taslak Sayfada Slot Değiştirme

Mevcut taslak sayfa değiştirme, doğrulama/uygulama sözleşmesinin içinde kalır:

POST /webadmin/api/content/validate
POST /webadmin/api/content/apply

Mevcut bir taslak sayfadaki bir veya daha fazla sayfaya ait slotu değiştirmek için mode: replace_existing_draft_page kullanın. İşlem, doğrulama için content.validate ve uygulama için content.apply gerektirir. Genel bir sayfa silme işlemi olmadığı için pages.delete gerektirmez.

Sayfa Çevirisi path değeri kanonik herkese açık URL'dir. Yeni planlar /contact, /features veya /docs/internal-content-api gibi yollar kullanmalıdır; /p/... yalnızca eski sürüm uyumluluğu içindir. Eğik çizgi içeren yollar segment segment normalize edilir; bu nedenle /docs/internal-content-api/, /docs/internal-content-api olur ve docsinternal-content-api biçimine indirgenmez. /webadmin, /webadmin/api, /cms, /search, /search.json, /contact-messages, /install gibi ayrılmış rota alanları ve ana ürün kimlik doğrulama rotaları herkese açık sayfa yolu olarak oluşturulamaz.

Örnek:

{
  "plan": {
    "mode": "replace_existing_draft_page",
    "site": "default",
    "locale": "en",
    "page": {
      "id": 9,
      "expected_path": "/contact",
      "status": "draft"
    },
    "replace_slots": {
      "main": [
        {
          "type": "plain_text",
          "translations": {
            "content": "Updated draft contact content."
          }
        }
      ]
    }
  }
}

Kurallar:

hedef sayfa draft durumunda olmalıdır
expected_path veya expected_updated_at zorunludur
expected_path, /p/... eski takma adını değil, kanonik herkese açık Sayfa Çevirisi yolunu kullanır
hedef sayfa istenen siteye ait olmalı ve dil (locale) o site için etkin olmalıdır
her slot sayfada mevcut olmalı ve sayfaya ait bloklar kullanmalıdır
Ortak Slot destekli slotlar temizlenmek yerine reddedilir
yalnızca adlandırılmış replace_slots içindeki bloklar kaldırılır
eski bloklar kaldırılır ve yeni bloklar tek bir işlemde (transaction) yazılır
sayfa revizyonları uygulamadan önce ve sonra kaydedilir
yayınlama, medya çekme/içe aktarma, geniş çaplı silme veya Ortak Slot atamasını temizleme gerçekleşmez

Kaynak Eşitleme Meta Verisi

İçerik planları, yapay zekâ/operatör doküman eşitleme iş akışları için sınırlı ve gizli bilgi içermeyen bir source_sync nesnesini kalıcı olarak saklayabilir. Rastgele sayfa ayarları reddedilir. Kabul edilen biçim şudur:

{
  "page": {
    "settings": {
      "source_sync": {
        "type": "markdown_documentation",
        "source_id": "webblocks-cms:docs/internal-content-api.md",
        "source_path": "docs/internal-content-api.md",
        "source_sha256": "64-character-lowercase-sha256",
        "managed_slots": ["main"],
        "last_synced_at": "2026-06-25T00:00:00Z"
      }
    }
  }
}

Uygulama bu meta veriyi sayfa ayarlarına kaydeder ve sayfa listesi/ayrıntı API yanıtları, gelecekteki eşleştirmeler için aynı izin listesindeki source_sync alanlarını gösterir. Token'ları, ortam değerlerini, yerel/sunucu mutlak yollarını veya diğer gizli bilgileri dahil etmeyin.

Açık Yayınlama Uç Noktaları

Yayınlama, içerik uygulamadan ayrıdır ve content.publish yeteneğine sahip bir token gerektirir.

POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks

POST /webadmin/api/pages/{page}/publish, sayfa kaydını yayınlar. Varsayılan yükü yalnızca sayfa içindir:

{
  "include_page_owned_blocks": false
}

Kurallar:

atlanan include_page_owned_blocks, false gibi davranır
include_page_owned_blocks: false yalnızca sayfa kaydını yayınlar; taslak veya incelemedeki blokları değiştirmez
include_page_owned_blocks: true, sayfanın ortak olmayan sayfa slotlarına ait taslak ve incelemedeki blokları, iç içe alt bloklar dahil yayınlar
halihazırda yayında olan bloklar değişmeden kalır
Ortak Slot destekli slotlar hariç tutulur ve yanıtta raporlanır
publish_shared_slots, include_shared_slot_blocks veya shared_slot_cascade gibi desteklenmeyen Ortak Slot kademeli alanları JSON 422 döndürür
yanıt; sayfa kimliği/durumu/yolu meta verilerini, sayfaya ait blokların dahil edilip edilmediğini, yayınlanan blok sayısını, hariç tutulan Ortak Slot özetlerini ve sayfa revizyon kimliğini içerir

POST /webadmin/api/pages/{page}/publish-page-owned-blocks, yalnızca yayınlanmamış sayfaya ait blokları yayınlar ve sayfa iş akışı durumunu değiştirmez. Aynı content.publish yeteneğini ve aynı Ortak Slot hariç tutma kuralını kullanır.

Yapay zekâ/operatör araçları, sayfa yayınlamanın tüm blok içeriğini herkese açık hale getirdiğini varsaymamalıdır. include_page_owned_blocks: true seçeneğini yalnızca kullanıcı, o sayfa için yayınlanmamış tüm sayfaya ait blokların yayınlanmasını açıkça onayladığında kullanın. Ortak Slot içeriği ayrı olarak incelenmeli ve yayınlanmalıdır.

İçerik Sözleşmesi Uç Noktası

GET /webadmin/api/content-contract, güvenilen yapay zekâ/operatör araçları için salt okunur bir keşif uç noktasıdır. API önekini, doğrulama/uygulama URL'lerini, yönetici önizleme URL şablonunu, güvenlik bayraklarını, keşif URL'lerini, önerilen sayfa oluşturma kalıplarını ve arındırılmış blok sözleşmesi meta verilerini döndürür.

Bu uç nokta genel CMS ürün davranışıdır. Kuruluma özgü gizli bilgileri, token değerlerini, ham Blade içeriklerini, mutlak dosya sistemi yollarını, özel sunucu yollarını veya siteye özgü talimatları döndürmemelidir. Blok sözleşmesi satırları; tanıtıcı (handle)/slug, etiket, kategori, durum, kapsayıcı ve alt blok desteği, çevrilebilir alanlar, ortak ayar alanları ve herkese açık işleyici (renderer) kök davranışını içerebilir.

Yapay zekâ araçları, bir plan oluşturmadan önce bu uç noktayı veya GET /webadmin/api/block-types uç noktasını çağırmalı ve yalnızca mevcut kurulumda bulunan tanıtıcıları kullanmalıdır.

contact_form sözleşmesi ek güvenli form meta verileri içerir: ayar şeması, çevrilmiş alanlar, herkese açık POST /contact-messages gönderim uç noktası, gerekli CSRF tarayıcı davranışı, sunucu doğrulama kuralları, CMS'ye ait gizli üretilmiş anti-spam denetim alanı, genel denetim alanı başarı davranışı, spam sınıflandırma/karantina notları, bildirimden önce depolama davranışı, alıcı yedek sırası, güvenli bildirim hatası kaydı ve /webadmin/contact-messages inceleme davranışı. Denetim alanı işleyici tarafından üretilir, normal ziyaretçi girdisinin parçası değildir ve API veya yapay zekâ/operatör araçları tarafından elle oluşturulmamalıdır. İletişim sayfası araçları; Trusted HTML, ham form işaretlemesi veya mailto: formları yerine bu yerleşik bloğu kullanmalıdır. Eski website alanı artık herkese açık İletişim Formu sözleşmesinin parçası değildir.

İnsan tarafından okunabilir Yapay Zekâ Sayfa Oluşturma Rehberi, paket-yerel kurulumlarda vendor/fklavyenet/webblocks-cms/docs/ai-page-building-guide.md yolunda gelir.

Faz 1 Kapsamı

Keşif Uç Noktaları

GET /webadmin/api
GET /webadmin/api/openapi.json
GET /webadmin/api/ai-guide
GET /webadmin/api/examples
GET /webadmin/api/examples/contact-page
GET /webadmin/api/examples/landing-page
GET /webadmin/api/sites
GET /webadmin/api/locales
GET /webadmin/api/page-layouts
GET /webadmin/api/block-types
GET /webadmin/api/content-contract

Sayfa Uç Noktaları

GET /webadmin/api/pages
GET /webadmin/api/pages/{page}
POST /webadmin/api/pages/{page}/slots/{slot}/shared-slot

Blok Uç Noktaları

GET /webadmin/api/blocks
GET /webadmin/api/blocks/{block}

Gezinme Uç Noktaları

GET /webadmin/api/navigation-menus
GET /webadmin/api/navigation-menus/{navigationMenu}
POST /webadmin/api/navigation-menus
POST /webadmin/api/navigation-menus/{navigationMenu}/items

Gezinme menüleri, mevcut CMS navigation_items.menu_key modelini kullanır. Faz 2A; primary, footer, mobile, legal ve docs gibi CMS ile gelen menü tanıtıcılarını destekler; ayrı bir menü tablosu eklemez. Bir gezinme menüsü oluşturmak, isteğe bağlı başlangıç öğeleriyle güvenli, site kapsamlı bir menü grubu oluşturmak olarak ele alınır. Zaten öğeleri olan bir site/menünün üzerine yazmayı reddeder.

Gezinme öğesi URL'leri; /, /about ve /contact gibi dahili yollar veya güvenli http/https URL'leri olabilir. API; javascript:, data:, protokol-göreli URL'leri, dizin gezinmesini (traversal), hatalı biçimli URL'leri, desteklenmeyen hedefleri ve boş etiketleri reddeder. Gezinme uç noktaları sayfa oluşturmaz, sayfa yayınlamaz, siteleri taramaz veya uzak URL'leri çekmez.

Ortak Slot Uç Noktaları

GET /webadmin/api/shared-slots
GET /webadmin/api/shared-slots/{sharedSlot}
POST /webadmin/api/shared-slots
POST /webadmin/api/shared-slots/{sharedSlot}/blocks

Ortak Slot oluşturma site kapsamlıdır ve aynı site için yinelenen tanıtıcıları reddeder. Ortak Slot blokları, sayfaya ait blokların kullandığı blok yükü yazıcısını yeniden kullanır; bu sayede dile ait metinler çeviri satırlarında kalır ve ortak ayarlar blok kaydı/ayar yolunda kalır. Medya içe aktarma ve medya atama bu fazın dışında kalır.

Sayfa Slotu Ataması

POST /webadmin/api/pages/{page}/slots/{slot}/shared-slot

Bu uç nokta, mevcut ve uyumlu, aynı siteye ait etkin bir Ortak Slot'u mevcut bir sayfa slotuna atar. Eksik sayfaları veya slotları oluşturmaz. Sayfayı yayınlamaz. Siteler arası, pasif ve uyumsuz Ortak Slotları reddeder. Ayrıca hâlâ sayfaya ait blokları olan bir slotu değiştirmeyi de reddeder; çünkü Faz 2A bu blokları otomatik olarak silmez veya değiştirmez.

İçerik Doğrulama / Uygulama Uç Noktaları

POST /webadmin/api/content/validate
POST /webadmin/api/content/apply

Faz 1 Güvenliği

yalnızca taslak
içerik uygulama üzerinden yayınlama yok
mevcut yayındaki içeriğin üzerine yazma yok
mode: replace_existing_draft_page dışında mevcut sayfaların veya blokların geniş çaplı üzerine yazılması yok
uzak veri çekme yok
medya indirme veya içe aktarma yok
henüz site oluşturma yok
içerik uygulama üzerinden yıkıcı sayfa silme yok
işlem kapsamlı taslak slot değiştirme dışında yıkıcı blok silme yok
henüz kaynak güncelleme, taşıma veya silme uç noktaları yok
Bearer token ile yapılan JSON yazmaları için tarayıcı oturumu, form veya CSRF gereksinimi yok
herkese açık kimliksiz erişim, asgari GET /webadmin/api önyükleme yanıtıyla sınırlıdır

JSON Hata Biçimi

API hataları yalnızca JSON'dur. Girişe yönlendirmemeli, CSRF sayfaları oluşturmamalı veya yığın izlerini (stack trace) açığa çıkarmamalıdır. Ortak alanlar:

{
  "ok": false,
  "code": "invalid_internal_api_token",
  "message": "Invalid internal API token.",
  "api_discovery_url": "/webadmin/api",
  "openapi_url": "/webadmin/api/openapi.json",
  "documentation_url": "/webadmin/api/ai-guide",
  "example_url": "/webadmin/api/examples/contact-page",
  "errors": []
}

Beklenen durum kodları:

eksik, geçersiz veya iptal edilmiş token'lar için 401
eksik yetenekler için 403
doğrulama hataları için 422

Kaynak API'si Örnekleri

Sayfaları Listele

GET /webadmin/api/pages

Sayfa Ayrıntılarını Oku

GET /webadmin/api/pages/{page}

Blokları Listele

GET /webadmin/api/blocks

Blok Ayrıntılarını Oku

GET /webadmin/api/blocks/{block}

İçerik Doğrulama / Uygulama Örneği

Aynı yük her iki uç noktaya da gönderilebilir:

POST /webadmin/api/content/validate
POST /webadmin/api/content/apply

Örnek İngilizce pazarlama ana sayfası taslağı:

{
  "plan": {
    "site": "example-site",
    "locale": "en",
    "layout": "default",
    "page": {
      "title": "Acme Studio",
      "path": "/",
      "status": "draft"
    },
    "slots": {
      "main": [
        {
          "type": "hero",
          "translations": {
            "title": "Plan, build, and publish with confidence",
            "subtitle": "Structured content for modern teams",
            "content": "Create a draft homepage from a validated content plan."
          },
          "children": [
            {
              "type": "button_link",
              "translations": {
                "title": "Start planning"
              },
              "settings": {
                "url": "/contact",
                "variant": "primary"
              }
            }
          ]
        },
        {
          "type": "section",
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "grid",
                  "settings": {
                    "columns": 3
                  },
                  "children": [
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Validate the whole draft before anything is written."
                              }
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "cta",
          "translations": {
            "title": "Ready to shape the next page?",
            "content": "Use structured plans for repeatable content creation."
          },
          "children": [
            {
              "type": "button_link",
              "translations": {
                "title": "Contact us"
              },
              "settings": {
                "url": "/contact",
                "variant": "primary"
              }
            }
          ]
        }
      ]
    }
  }
}

Doğrulama Kuralları

site tanıtıcısı veya kimliği çözümlenebilmelidir
dil (locale) mevcut olmalı ve hedef site için etkin olmalıdır
yerleşim mevcut olmalıdır
yol çakışması sayfa oluşturmayı engeller
blok türü yayında ve kullanılabilir olmalıdır
alt blok desteği, mevcut olduğunda blok sözleşmelerine uymalıdır
kullanıcıya görünen metin çeviri satırlarına aittir
ortak ayarlar ortak kalır
bilinmeyen güvensiz ayarlar reddedilir
zararsız bilinmeyen ayarlar tutarlı biçimde uyarı verebilir veya yok sayılabilir
uygulama, yazmadan önce yeniden doğrular
uygulama işlemseldir (transactional)
İçerik uygulama; yayınlama, site oluşturma, medya içe aktarma, uzak veri çekme, desteklenmeyen üzerine yazma, desteklenmeyen değiştirme ve silme işlemlerini reddetmeye devam eder
daha sonraki bir faz açık, taslak-güvenli değişiklik sözleşmeleri eklemedikçe gezinme ve Ortak Slot oluşturma yalnızca oluşturma amaçlıdır

Yanıt Biçimi

Yanıtlar öngörülebilir JSON olmalıdır:

{
  "ok": true,
  "writes": [],
  "data": {
    "page": {
      "id": 123,
      "title": "Product Overview",
      "status": "draft",
      "edit_url": "/webadmin/pages/123/edit"
    }
  },
  "normalized_plan": {},
  "warnings": [],
  "errors": []
}

Doğrulama hataları bir yol ve mesaj içermelidir:

{
  "ok": false,
  "writes": [],
  "data": null,
  "normalized_plan": {},
  "warnings": [
    {
      "path": "plan.slots.main.1.settings.theme",
      "message": "Unknown harmless setting ignored."
    }
  ],
  "errors": [
    {
      "path": "plan.page.path",
      "message": "A page already exists at this path for the selected site and locale."
    }
  ]
}

Oluşturulan veya güncellenen CMS kaynakları için yararlı olduğunda edit_url ekleyin.

Faz 2A Plan Bölümleri

İçerik planları, mevcut sayfa/slot planının yanında navigation_menus, shared_slots ve page_slot_shared_slots içerebilir. validate hiçbir şey yazmaz. apply, tüm geçerli bölümleri tek bir işlemde yazar ve sonraki herhangi bir bölüm başarısız olduğunda tüm planı geri alır.

{
  "plan": {
    "site": "default",
    "locale": "en",
    "layout": "default",
    "page": {
      "title": "Homepage Draft",
      "path": "/",
      "status": "draft"
    },
    "slots": {
      "main": []
    },
    "navigation_menus": [
      {
        "handle": "primary",
        "label": "Primary Navigation",
        "items": [
          {
            "label": "Home",
            "url": "/",
            "target": "_self",
            "sort_order": 10
          }
        ]
      }
    ],
    "shared_slots": [
      {
        "handle": "site-header",
        "label": "Site Header",
        "slot": "header",
        "blocks": []
      }
    ],
    "page_slot_shared_slots": [
      {
        "page": "created",
        "slot": "header",
        "shared_slot": "site-header"
      }
    ]
  }
}

page_slot_shared_slots[].page, created kullanarak aynı planın oluşturduğu sayfaya veya mevcut bir sayfa kimliğine başvurabilir. shared_slot, aynı planda daha önce oluşturulmuş bir Ortak Slot'a veya aynı siteye ait mevcut bir Ortak Slot tanıtıcısına başvurabilir.

Gelecek Fazlar

Faz 2B

gezinme ve Ortak Slot blokları için isteğe bağlı taslak-güvenli güncelleme/taşıma uç noktaları
gerektiğinde açık ve güvenli temizleme/değiştirme sözleşmeleri
yalnızca genel CMS davranışı olarak kaldıkları sürece daha derin üst bilgi/gezinme çubuğu oluşturma yardımcıları

Faz 3

gerektiğinde taslak-güvenli doğrudan sayfa/blok düzenlemeleri için kaynak uç noktaları
kontrollü taslak güncellemeleri veya taslak içerik değiştirme
sayfa varlıkları
yalnızca mevcut medya kimliğiyle medya

Faz 4

ayrı tasarıma ve izinlere sahip olduklarında yayınlamanın ötesinde ek açık iş akışı geçişleri

Yapay Zekâ Kullanım Rehberi

önce siteleri, dilleri (locale), yerleşimleri ve blok türlerini keşfedin
uygulamadan önce doğrulayın
taslak içerik oluşturun
docs/public-block-render-markup.md içindeki yapılandırılmış blokları tercih edin
incelenmiş bir yedek çözüm dışında Safe HTML kullanmaktan kaçının
üretilen herkese açık metni hedef dilde tutun; örneğin İngilizce bir ana sayfa için İngilizce

Sınırlar

CMS çekirdeğinde OpenAI veya LLM entegrasyonu yok
tarama veya veri çekme yok
rastgele içe/dışa aktarma ikamesi yok
otomatik yayınlama yok
Faz 1'de yıkıcı silme yok
ana ürünün /admin rotasına ilişkin varsayım yok
/cms rota öneki kullanımı yok
QuizTem'e özgü çalışma zamanı kodu yok; QuizTem ana sayfa üretimi, bu genel CMS API'si için daha sonraki bir tüketici kullanım senaryosudur