Dahili İçerik API'si

Internal Content API, güvenilir yapay zeka ve operatör araçlarına yönelik güvenli bir CMS API'dir. Bu araçların CMS içerik sözleşmelerini incelemesine, taslak öncelikli içerik oluşturmasına, mevcut taslak sayfalarındaki sayfaya ait belirli alanları değiştirmesine, yapılandırılmış JSON aracılığıyla açık yayınlama işlemlerini yürütmesine ve tarayıcı yöneticisi kullanıcı arayüzünde oturum açmaya, silmeye veya otomatikleştirmeye gerek kalmadan görsel QA için izin verilenler listesindeki yönetici oluşturma anlık görüntülerini talep etmesine olanak tanır.

Phase 1, doğrulanmış içerik planları aracılığıyla salt okunur içerik keşfi ve taslak sayfa oluşturma için belirteç korumalı, yalnızca JSON, halka açık olmayan API olarak uygulanır. Aşama 2A, gezinme menüleri, Shared Slots ve açık sayfa yuvası Shared Slot ataması için güvenli temeller ekler. Aşama 2B, mevcut sayfalardaki sayfaya ait alan içeriği için kontrollü yalnızca taslak değişimini ekler. Yayınlama uç noktaları açıktır ve content.publish gerektirir; içerik başvurusu ilk taslak olarak kalır ve yayınlanmaz. API kasıtlı olarak dar kalıyor: uzaktan getirme yok, içerik uygulaması aracılığıyla geniş sayfa silme yok, Shared Slot destekli yuvaların değiştirilmesi yok ve Shared Slot basamaklı yayınlama yok.

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.

Kanonik önek şudur:

Bu, kısa ve tanıdık bir API segmenti kullanırken API'yi CMS yönetici sınırları içinde tutar. /webadmin/api/pages ve /webadmin/api/blocks.

gibi kaynak tarzı uç noktalar doğrudan bu önek altında bulunmalıdır.

İçeriği planlamadan önce paketteki bilgileri okuyunCMS EnvanteriileGET /webadmin/api/inventory. Bu, blok başına tasarım ve yazma sözleşmesidir ve bir yapay zekanın okuması gereken ilk belgedir.htmlblok yalnızca insanlara yöneliktir: API aracılığıyla okunabilir durumda kalır, ancak ona dokunan her API mutasyonu,422ve kararlı kodblock_type_not_api_writableve hiçbir yetenek bunu geçersiz kılmaz. bir içinapplicationblok, önce hazır bir tanımı ve onun ayarlar şemasını keşfedinGET /webadmin/api/applications; API yazma işlemleri kayıtlı uygulamalara referans verebilir ancak yürütülebilir kod veya dosya yollarını tanıtamaz.

API bulmanın başlangıcı:

Kimliği doğrulanmamış arayanlar yalnızca genel güvenli önyükleme JSON alır. Kimliği doğrulanmış arayanlar, güvenli ürün sürümü meta verilerinin yanı sıra OpenAPI, AI kılavuzu, içerik sözleşmesi, örnekler, içerik doğrulama/uygulama, sayfalar, bloklar, medya, gezinme ve Shared Slots bağlantılarına ulaşır. Harici yapay zeka/operatör araçları, CMS deposunu veya yerel paket belgelerini okumak yerine bu canlı keşif yanıtından başlamalıdır.

Plan tabanlı içerik işlemleri kullanımı:

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

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

CMS'nin iki belirteç yüzeyi vardır. Editörler, Site yöneticileri ve Süper yöneticiler, Profile -> Personal API Tokens'den kişisel API belirteçleri oluşturur; bu belirteçler, canlı rol, site, iş akışı, ağ ve yetenek sınırları dahilinde sahipleri olarak hareket eder. Süper yöneticiler, açıkça yetkilendirilmiş kurulum düzeyinde otomasyon için System -> API Tokens'den Sistem API belirteçleri oluşturur. CMS, cms_api_tokens veritabanı tablosunda yalnızca bir SHA-256 karmasını ve güvenli bir önizlemeyi saklar. Düz jeton, oluşturulduktan hemen sonra bir kez gösterilir ve bir daha asla gösterilmez.

Tek seferlik belirteç paneli, hem tam belirteç hem de oluşturulan yerel .env örneği için kopyalama kontrolleri sağlar. Kopya geri bildirimi erişilebilir bir şekilde duyurulur ve tarayıcı uygulaması, modern Clipboard API.

olmayan ortamlar için bir geri dönüş içerir Eski varsayılan sayfa oluşturma özelliği seti ile oluşturulan

Tokenler, çalışma zamanında salt okunur admin.render özelliği için uygun olarak kabul edilir; böylece güvenilir operatör araçları, güncellemeden sonra jetonu döndürmeden izin verilenler listesine eklenen yönetici görsel QA anlık görüntülerini kullanabilir. Önceki varsayılan seti içermeyen dar özel belirteçler kısıtlı kalır.

Her iki jeton ekranı da her jeton için bir geçmiş eylemi içerir. Bu belirteç için en son 10 API etkinlik kaydını içeren bir WebBlocks UI modelini açar. Etkinlik kayıtları kasıtlı olarak küçüktür: istek süresi, durum, yöntem, sorgu dizesi içermeyen yol, rota adı, bir yetenek koruması değerlendirildiğinde gereken yetenek, IP ve kısa bir kullanıcı aracısı değeri. CMS, istek gövdelerini, sorgu dizelerini, yanıt gövdelerini, taşıyıcı belirteç değerlerini, belirteç karmalarını veya belirteç önizlemelerini etkinlik satırlarında depolamaz. Daha eski etkinlik satırları otomatik olarak budanır, böylece her jeton yalnızca en son 10 kaydı tutar.

Kullanıcılar kendi kişisel belirteçlerini düzenleyebilir, iptal edebilir ve silebilir; Süper yöneticiler Sistem belirteçlerini yönetir. Düzenleme, sırrı açığa vurmadan politika meta verilerini değiştirir. İptal işlemi, denetim satırını korurken API erişimini anında devre dışı bırakır. Bir jetonun silinmesi, onu ve etkinlik geçmişini kalıcı olarak kaldırır.

Yerel yapay zeka ve operatör araçları, oluşturulan jetonu güvenilir bir operatör gizli deposunda saklamalıdır.

Yerel operatör yapılandırmasında Internal Content API temel URL'sini kullanın:

CMS çalışma zamanı WEBBLOCKS_CMS_INTERNAL_API_TOKEN gerektirmez.

Kimlik doğrulama kuralları:

• Eksik, yanlış veya iptal edilen jetonlar geri döner JSON 401
• İptal edilen jetonlar anında çalışmayı durdurur
• Belirteçler hiçbir zaman günlüklerde, teşhislerde, destek raporlarında, testlerde veya belge örneklerinde yazdırılmamalıdır
• belirteç karşılaştırması sabit zamanlı bir karşılaştırma kullanmalıdır
• Başarılı API istekleri belirteci günceller last_used_at ve last_used_ip
• başarılı API istekleri aynı zamanda operatör denetim bağlamı için kesilmiş bir kullanıcı aracısını da saklar
• normal kaynak yanıtları ve tüm hatalar JSON; İzin verilenler listesine eklenen görsel KG rotaları, yalnızca arayan kişi açıkça bir HTML biçimi

talep ettiğinde doğrudan HTML döndürebilir

Örnek istek:

Token sahipleri, kişisel bir token oluştururken veya düzenlerken yetenekleri seçerler; Süper yöneticiler Sistem belirteçleri için aynısını yapar. Düzenleme sırrı açığa çıkarmaz veya döndürmez. Kişisel belirteç formu yalnızca sahibinin geçerli rolünün devredebileceği yetenekleri gösterir ve her istek, canlı rolü yeniden kontrol eder. Discovery, belirteç değerini, belirteç karmasını veya belirteç önizlemesini döndürmeden etkili yetenekleri ortaya çıkarır. Standart sayfa oluşturma belirteçleri şu yetenekleri kullanır:

• content.read
• content.validate
• content.apply
• navigation.write
• shared-slots.write
• media.read
• site-settings.write

AGelişmiş yetenekler ayrı seçeneklerdir ve varsayılan olarak seçilmez:

• navigation.delete
• shared-slots.delete
• domains.write
• domains.delete
• site-assets.read
• site-assets.write
• engagement.read
• engagement.moderate
• plugins.read
• plugins.install
• plugins.manage
• plugins.setup
• plugins.uninstall
• commerce.read
• commerce.products.write
• commerce.orders.read
• media.write
• media.upload
• media.replace
• media.move
• media.delete
• content.publish
• pages.delete
• content.blocks.delete
• backups.create
• page-assets.write

Write uç noktaları, sunucu tarafında ilgili yeteneği kontrol eder. Eksik yetenekler, api_discovery_url, openapi_url, documentation_url ve example_url rehberliğiyle JSON 403'yi döndürür. Normal sayfa oluşturma belirteçleri, gezinme silme, Shared Slot silme, içerik yayınlama, eklenti yükleme/yönetme/kurulum/kaldırma veya sayfa silme gibi yıkıcı yetenekler içermemelidir. Yorumları Okumak/Derecelendirme geri bildirimi açık engagement.read gerektirir; Yorum durumunu değiştirmek açık engagement.moderate gerektirir. Eklenti yaşam döngüsü otomasyonu açık eklenti yetenekleri gerektirir ve WebBlocks Ticari ürün/sipariş API erişimi açık ticari özellikler gerektirir.

Her /webadmin/api rotası ve eski /admin-api rotaları iki istek bütçesini paylaşır. İstemci başına IP ve belirteç bütçesi varsayılan olarak dakikada 120 istektir (CMS_INTERNAL_API_RATE_LIMIT_PER_MINUTE). Bağımsız bir IP geri durdurma, geçersiz belirteç girişimleri de dahil olmak üzere, sağlanan tüm belirteçler ve API yolları (CMS_INTERNAL_API_IP_RATE_LIMIT_PER_MINUTE) genelinde dakikada 300 isteğe varsayılan olarak ayarlanır. Tokenların döndürülmesi bu geri döndürmez kilidi sıfırlamaz. Her iki bütçenin aşılması, Retry-After başlığına sahip 429 değerini döndürür. Pozitif olmayan yapılandırma değerleri varsayılanlara geri döner.

GET /webadmin/api/openapi.json'de x-rate-limit'den canlı bütçeleri okuyun: requests_per_minute belirteç ve IP bütçesidir ve ip_requests_per_minute bağımsız IP bütçesidir. IP paylaşan istemciler, birleşik istek hacmini koordine etmelidir.

Etkin bir Süper yönetici, Sistem → Ayarlar → Güvenlik altında her iki bütçeyi de geçersiz kılabilir. Veritabanı destekli panel değerleri, kurulum yapılandırmasına göre önceliklidir ve mevcut sayaçları sıfırlamadan sonraki isteklere uygulanır. Yükleme varsayılanlarını kullan, güvenlik geçersiz kılmalarını kaldırır ve yapılandırılmış bütçeleri geri yükler. Kaydetme veya geri yükleme .env veya sunucu ayarlarını düzenlemez. İstek bütçeleri 1.000.000'a kadar pozitif tam sayıları kabul eder. Kişisel tokena özgü limitler ek limitler olmaya devam ediyor; bunları değiştirmek bu paylaşılan API bütçelerini değiştirmez.

Sitenin önündeki barındırma, proxy veya CDN katmanları, CMS'nin uyguladığından daha düşük bir sınır uygulayabilir; bu nedenle, tam site çeviri geçişi gibi toplu bir istemcinin, hemen yeniden denemek yerine kendi hızını ayarlaması ve 429 üzerinde geri adım atması gerekir.

Kişisel belirteçler ayrıca dakikada 30, 60, 120 veya 300 istekten oluşan yapılandırılabilir bir tavana sahiptir; Kaydedilmiş değeri olmayan mevcut kişisel belirteçler 60'ı kullanır. Bunlar aynı zamanda tam IPv4/IPv6 adreslerine veya CIDR ağlarına erişimi de kısıtlayabilir. Kimliği doğrulanmış keşif, bu ayarları token.network_policy altında bildirir. Laravel'nin çözümlenen istemci IP'si yetkili olduğundan, ters proxy veya CDN'nin arkasındaki ana bilgisayarlar, izin verilenler listesine güvenmeden önce yalnızca gerçek proxy adreslerine ve iletilen üstbilgilere güvenmelidir.

API'nin birbirini tamamlayan iki modu vardır.

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/locale-options, seçilmiş standart dil yerel ayar seçici kataloğunu düz bir locale_options listesi olarak döndürür. API araçları, normal bir dil yerel ayarı oluştururken code ve name dizelerini icat etmek yerine döndürülen locale_option'yi seçmelidir.

POST /webadmin/api/locales ve PATCH /webadmin/api/locales/{locale}, site-settings.write gerektirir ve yalnızca güvenli yerel ayar alanlarını kabul eder: locale_option, code, name, is_default ve is_enabled. locale_option gönderildiğinde standart katalogdan standart kod ve İngilizce ad kopyalanır; doğrudan code ve name, kontrollü ülke değişkeni veya özel/operatör durumları için kullanılabilir olmaya devam ediyor. is_default=true'nin ayarlanması, yerel ayarın etkinleştirilmesini zorlar ve normal CMS yerel ayar değişmezi aracılığıyla önceki varsayılanların değerini düşürür. Geçiş araçları, yeni tek yerel ayarlı Almanca yüklemesini en'den de'ye değiştirmek gibi yalnızca dil kurulum hatasını düzeltirken mevcut yerel ayar kimliğine yama yapmalıdır; böylece mevcut sayfa, blok ve site yerel ayarı ilişkileri kimliklerini korur.

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

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

POST /content/apply, isteğe bağlı bir üst düzey create_restore_point: true bayrağını kabul eder. Ayarlandığında CMS, planı uygulamadan önce geri yükleme noktası olarak tam sistem yedeğini (veritabanı artı yüklemeler) alır, böylece yapay zeka tarafından oluşturulan bir uygulama yanlış giderse operatör System -> Backups'den geri dönebilir.

Kurallar:

• adanmış gerektirirbackups.createvarsayılan sayfa oluşturma setinin parçası olmayan yetenek; bu olmadan istek JSON değerini döndürür403
• önce plan doğrulanır, dolayısıyla geçersiz bir plan döndürülür422boşa harcanan bir yedekleme oluşturmadan
• yedekleme oluşturulamıyorsa uygulama iptal edilir ve JSON değeri döndürülür409; talep edilen güvenlik ağı olmadan içerik asla uygulanmaz
• başarı durumunda başvuru yanıtı şunları içerir:restore_pointyedeklemeyle nesneid,type(content_apply),label,status, Vecreated_at
• yedekleme tam ve senkronize olduğundan gözle görülür bir gecikmeye neden olur; yüksek frekanslı otomasyon için değil, büyük veya yıkıcı uygulamalar için kullanın

API kasıtlı olarak yalnızca geri yükleme noktası oluşturulmasını açığa çıkarır. Yedeklemelerin geri yüklenmesi, indirilmesi ve silinmesi, operatör yöneticisi kullanıcı arayüzünde kalır ve API.

belirtecinin bir parçası değildir.

Bu uç noktalar sırasıyla plugins.read, plugins.install, plugins.manage, plugins.setup veya plugins.uninstall gerektirir. Taşıyıcı kimlik doğrulamasıyla çalışırlar ve kimliği doğrulanmış bir tarayıcı oturumu gerektirmezler. Manuel kurulum uç noktası, doğrulanmış bir eklenti ZIP yapıtını kabul eder. Katalog listesi/ayrıntı istekleri plugins.read gerektirir; katalog kurulumu ve güncellemesi plugins.install gerektirir ve CMS katalog istemcisinin, uyumluluk kontrollerinin, yapı boyutu/ZIP doğrulamasının ve SHA-256 doğrulamasının yeniden kullanılmasını gerektirir. Katalog güncellemesinin yüklü sürümden daha yeni olması gerekir ve eklentinin önceki etkin durumunu yalnızca başlangıç ​​doğrulaması ve veritabanı kurulumu başarılı olduktan sonra geri yükler. Her iki yükleme yolu da yeni yüklenen eklentiyi varsayılan olarak devre dışı bırakır. CMS 1.92.0'den bu yana kurulum, güncellemeler ve etkinleştirme, gerekli eklenti veritabanı değişikliklerini otomatik olarak uygular. Başarısız bir kurulum, eklentiyi açık bir yeniden deneme eylemiyle devre dışı bırakır. Panel/API, durumu değiştirmeden önce HTTP 409 ve plugin_incompatible ile uyumsuz eklentileri etkinleştirin ve reddedin. CMS 1.94.0 zorunlu bir yalıtılmış başlangıç ​​denetimi, tutulan paketler, çalışma zamanı karantinası ve /webadmin/plugin-recovery ekler; kurtarma koşulları için Ekleme Sistemi'ye bakın. Kaldırma, manuel olarak yüklenen eklentilerin devre dışı bırakılmasıyla sınırlıdır ve eklentiye ait tabloları korur.

WebBlocks Commerce etkinleştirildiğinde ve kuruluma hazır olduğunda, güvenilir araçlar ürünleri oluşturabilir/listeleyebilir ve siparişleri okuyabilir:

Commerce ürün okumaları commerce.read gerektirir, ürün yazmaları commerce.products.write gerektirir ve sipariş okumaları commerce.orders.read gerektirir. Eklenti devre dışıysa veya kurulum geçişleri çalıştırılmadıysa Commerce uç noktaları, ham veritabanı hatası yerine kurulum kılavuzuyla birlikte JSON 409 döndürür.

Eklentiye ait webblocks-commerce-buy-button bloğu, yalnızca eklenti etkinken GET /webadmin/api/block-types ve GET /webadmin/api/content-contract'den keşfedilebilir. Ayarları GET /webadmin/api/commerce/products'den settings.commerce_product_id'yi gerektirir; doğrulama/uygulama eksik, bilinmeyen veya etkin olmayan ürün kimliklerini reddeder. Ödeme genel Ticaret/PayPal akışında kalır. CMS API, ürünler ve sayfa blokları oluşturur ancak kart verilerini toplamaz veya kart giriş akışını başlatmaz.

Tek bir işlemde tam sayfa oluşturmak için içerik doğrulama/uygulama özelliğini kullanın. Artımlı taslak düzenlemeleri için, sayfaya ait blokları tek tek eklemek, yeniden sıralamak veya silmek için Page Blok Topolojisi API'yi kullanın. Mevcut blok güncelleme uç noktasını yalnızca blok zaten mevcut olduğunda ve değişiklik güvenli bir yerel alanla eşlendiğinde kullanın:

Son nokta content.apply gerektirir. Blok bir Shared Slot kaynak ağacının parçasıysa belirtecin ayrıca shared-slots.write.

'ye sahip olması gerekir.

Desteklenen alanlar kasıtlı olarak daraltılmıştır:

• media_idveyaasset_idiçinnavbar-brandVesidebar-brandlogo medya
• media_idveyaasset_idiçinhero,section,card,cta, Vecontent_headerarka plan medyası
• settings.url
• settings.target
• settings.aria_label
• settings.background_position
• settings.background_overlay
• settings.show_searchiçinheader-actions
• settings.show_mode_toggleiçinheader-actions
• settings.show_accent_toggleiçinheader-actions
• settings.show_language_switcheriçinheader-actions
• gibi metin çevirilerititleVesubtitle
• aracılığıyla görüntü bloğu çevirileritranslations.image.alt_text,translations.image.captionveya kısaltmasıtranslations.alt_textVetranslations.caption
• Resim Galerisi Görüntüleyicisi gruplama yoluylasettings.viewer_enabledve bir küçük harfsettings.viewer_group; mevcut bir CMS Galeri Görüntüleyicide bir grup oluşturmayı paylaşan etkin, bağlantısız Görüntü blokları, bağımsız konumlarda kalırken
• iletişim formu çevirileri aracılığıylatranslations.contact_form.submit_labelVetranslations.contact_form.success_message, veya kısaltmayla aynı adlar, yanındatitleVecontent
• url
• variant

Çevrilen alanlar, istekteki yerel ayar için blok türünün ait olduğu çeviri ailesine yazılır (locale atlandığında site varsayılan yerel ayarı):

A alanı 422 ve unsupported_block_translation_fields koduyla reddedilir ve çeviri ailesi olmayan bir blok türü translations'yi unsupported_block_translations ile doğrudan reddeder - ikisi de hiçbir şeyin okuyamayacağı metin tablosuna yazılmaz. Bloğun sitesinin etkinleştirmediği bir yerel ayar invalid_block_translation_locale ile reddedilir. Saklanan satırlar, aile tarafından anahtarlanan block.translations altında döndürülür.

Görüntü blokları için, açıkça boş bir dize veya null, seçilen yerel ayarın caption veya alt_text'sini temizler; title ve subtitle takma adları aynı davranışa sahiptir. Atlanan alanlar kayıtlı değerlerini korur. Editoryal görsel metninin temizlenmesi, diğer dilleri, medya referanslarını ve dinamik bağlamaları korur. Boş bir editoryal başlık, dinamik ciltleme bir şekil başlığı sağlamadığı sürece şekil başlığı oluşturmaz; alternatif metin için mevcut Medya/dinamik kaynak geri dönüşü geçerliliğini korur.

A iletişim formunun submit_label ve success_message'si çeviridir, ayar değildir: formun düğmesini ve onay metnini yerelleştirmenin tek yoludur ve settings.

aracılığıyla ayarlanamazlar

Uç nokta, parent_id, slot_type_id, block_type_id, type, sort_order ve children gibi topoloji ve veritabanı uygulama alanlarını reddeder. Ayrıca ham HTML'yi, uzak medya URL'lerini ve kaynak URL'lerini de reddeder. Mevcut medya, CMS Medya Kitaplığı'ndan seçilebilir ancak bu API, yeni uzak medyayı içe aktarmaz veya indirmez.

Eörnek:

Mevcut bir Görüntü bloğu için, yerele ait görüntü çeviri satırını şununla güncelleyin:

Artımlı taslak sayfa düzenlemesi için, sayfaya ait blok topolojisi, tam içerik planı göndermeden tek seferde bir işlemle değiştirilebilir:

{slot}, sayfaya ait bir slot eklentisidir. Bu uç noktalar kasıtlı olarak taslak açısından güvenli ve dardır:

• yalnızca taslak sayfalarda çalışırlar; taslak olmayan bir sayfa JSON 409'yi page_not_draft koduyla döndürür. İçeriği kullan, yayınlanan sayfalar için aşamalı güncellemeleri uygula.
• yalnızca sayfaya ait alanlarda çalışırlar; Shared Slot destekli bir yuva JSON 422 değerini döndürür. Shared Slot içeriği için Shared Slot uç noktalarını kullanın.
• Bilinmeyen bir sayfa yuvası JSON 404'yi döndürür.

POST .../blocks, içerik uygulandığında aynı normalleştirilmiş blok yükünü kullanarak bir blok ekler (type, settings, translations ve iç içe children). draft durumuyla yeni bloklar oluşturulur ve yuvanın sonuna eklenir. Aynı yuvadaki mevcut bir konteyner bloğunun altına eklemek için parent_id'yi iletin; ebeveyn çocukları kabul etmelidir. Oluşturma ve yeniden sıralama için content.apply.

gerekir

PATCH .../blocks/reorder bir kardeş grubu yeniden numaralandırır. blocks dizisi, tek bir üst grubun her kardeş kimliğini istenen sırayla tam olarak bir kez içermelidir; ebeveyn gönderilen bloklardan türetilir. Kısmi bir grup gönderildiğinde JSON 422.

değeri döndürülür

DELETE .../blocks/{block} bloğu ve alt ağacının tamamını kaldırır ve deleted_blocks_count değerini döndürür. Silme işlemi, varsayılan sayfa oluşturma özelliği kümesinin parçası olmayan özel content.blocks.delete yeteneğini gerektirir. Shared Slot kaynak blokları bu uç nokta aracılığıyla silinemez.

Her yazma işlemi bir sayfa revizyonunu yakalar, böylece taslak düzenlemeler geri alınabilir.

hero ve cta, eylem düğmeleri düz button_link çocukları olan sıradan kaplardır; bunları diğer herhangi bir iç içe geçmiş blok gibi children altında bildirin. Yaygın bir veya iki düğmeli durum için kısa yol olarak iki isteğe bağlı blok alanı kalır:

Her iki alan da eylemi ayarlamadan bırakmak için gerekli label ve gerekli url veya null'ye sahip bir nesneyi kabul eder. URL'ler güvenli bir dahili yol veya http(s) URL'si olmalıdır. Kısa yol, ilk iki button_link alt öğesini yazar; dolayısıyla sonuç, düzenleyicinin elle eklediği düğmelerden ayırt edilemez. Çocukları açıkça bildirmek kanonik biçimdir ve ikiden fazla düğme yazmanın tek yoludur. primary_cta veya secondary_cta'nin başka herhangi bir blok türünde gönderilmesi reddedilir.

Alanlar, blok yükünün kabul edildiği her yerde çalışır: içerik doğrulama/uygulama planları, POST /pages/{page}/slots/{slot}/blocks ve POST /shared-slots/{sharedSlot}/blocks.

Page kurtarma, inceleme-önizleme-uygulama iş akışını kullanır. Doğrudan geri yükleme uç noktası yoktur.

• GET /webadmin/api/pages/{page}/versions, kayıtlı sürümleri sayfa durumları, denetim alanları ve önceki sürümdeki değişikliklerin özetiyle birlikte listeler. GET .../versions/{version} tam karşılaştırmayı ve referans durumu sonucunu döndürür. Her ikisi de content.read gerektirir.
• POST .../versions/{version}/candidate, content.apply gerektirir. Anlık görüntüden özel bir taslak adayı oluşturur ve tarayıcı önizleme URL'sini döndürür. Kaynak sayfası değiştirilmez.
• POST .../version-candidates/{candidate}/apply, hem content.apply hem de content.publish gerektirir. Aday hazırlandıktan sonra kaynak sayfa değiştiyse JSON 409 ve restore_candidate_stale koduyla başvuru reddedilir. Başarılı bir uygulama, normal geri yükleme öncesi ve sonrası güvenlik sürümlerini oluşturur ve teknik taslağı kaldırır.
• DELETE .../version-candidates/{candidate}, content.apply gerektirir; kaynak sayfayı değiştirmeden adayı kaldırır.

Adaylar, normal sayfa bulma ve site dışa aktarma işlemlerinde kasıtlı olarak yer almıyor. Araçlar her zaman sürümü incelemeli, bir aday hazırlamalı, preview_url'yi oluşturmalı veya açmalı ve ancak açık operatör onayından sonra apply_url'yi çağırmalıdır.

GET /webadmin/api/pages/{page}/render, content.read gerektirir ve tarayıcı yöneticisi önizlemesinin oluşturduğu sayfayı tam olarak döndürür: taslak bloklar dahil, X-Robots-Tag: noindex, nofollow ve hiçbir zaman genel yol üzerinden değil, dolayısıyla onunla ilgili hiçbir şey hiçbir şey yayınlamaz.

AJSON zarfı yerine işaretlemenin kendisi için ?format=html'yi ve belirli bir çeviriyi oluşturmak için ?locale=de'yi ekleyin; varsayılan, sitenin varsayılan yerel ayarıdır. Sayfanın çevirisi olmayan bir yerel ayar, page_translation_missing ile 422'yi ve sahip olduğu yerel ayarları döndürür. Shared Slot kaynak sayfaları iskeleyi düzenliyor ve tarayıcı yöneticisinin kendi 404'üyle eşleşen page_not_renderable ile 422'yi döndürüyor.

Rendering, bu uç nokta var olmadan önce zaten erişilebilir durumdaydı: GET /webadmin/pages/{page}/preview, content.read ile bir Bearer jetonunu ve yönetici oturumunu kabul ediyor ve hala kabul ediyor. API, bir JSON zarfı ve keşif/OpenAPI bağlantıları ekler. Tarayıcı önizlemesi aynı zamanda locale kodunu da kabul eder: dilin site için etkinleştirilmesi ve sayfa çevirisinin olması gerekir. Bunu atlamak varsayılan dili korur. Her iki önizleme de, oluşturmayı engellemek için seçilen dili geçirir; içeriği kaydetmez veya yayınlamaz.

Her iki durumda da, bir sayfanın tamamlandığını bildirmeden önce oluşturun. İçerik uygulaması, neyin depolandığını belirtir ancak bu, oluşturulanla aynı değildir: alt öğesi olmayan bir sarma bloğu, yanlış Shared Slot'ye atanmış bir yuva veya planın varsaydığı yuvaların olmadığı bir düzen, temiz bir şekilde uygulandığını ve yine de kimsenin istemediği bir sayfa ürettiğini gösterir.

Page çevirileri kendi yerelleştirilmiş sayfa kimliğine ve sayfa düzeyinde SEO ve Açık Grafik geçersiz kılmalarına sahiptir. İçerik uygulaması, bir sayfa oluşturduğunda bir yerel ayar için bir çeviri satırı yazar; bu uç noktalar, o satırın nasıl tekrar okunduğunu ve daha sonra değiştirildiğini gösterir.

GET /webadmin/api/pages/{page}/translations, name, slug, path, seo_title, seo_description, seo_keywords ile her çeviriyi bir sayfada listeler. list_excerpt, og_title, og_description ve og_image_media_id. list_excerpt, bir Sayfa Listesi bloğunun bir listeleme kartında bu sayfanın başlığı altında gösterdiği her yerel cümledir; 300 karakterle sınırlıdır ve boşaldığında SEO açıklamasına geri döner. Artık GET /webadmin/api/pages/{page}.

'deki her çeviride aynı alanlar görünüyor

POST /webadmin/api/pages/{page}/translations/{locale}gerekliliklercontent.applyve sayfa sitesi için zaten etkinleştirilmiş bir yerel ayar için çeviri ekler.{locale}segment bir yerel ayar kodunu veya sayısal bir kimliği kabul eder. Sadecenamegereklidir: atlaslugVepathve her ikisi de tam olarak tarayıcı yöneticisinin bunları türettiği gibi addan türetilmiştir. Sayfanın zaten döndürdüğü bir yerel ayar için çeviri oluşturma422kod ilepage_translation_exists.

PATCH /webadmin/api/pages/{page}/translations/{translation}, content.apply gerektirir ve yalnızca isteğin taşıdığı alanları yazar; böylece bir araç, sayfa kimliğini yeniden göndermeden seo_description'yi ayarlayabilir. İsteğe bağlı bir alanı temizlemek için null gönderin.

Slug ve yol her zaman birlikte hareket eder. path'nin gönderilmesi, bilgi son segmentinden yeniden türetilir; slug'nin tek başına gönderilmesi sayfayı /{slug}'ye taşır. Yollar kurallı hale getirilir, ayrılmış CMS ve ana makine rotalarına göre kontrol edilir ve site ve yerel ayar için benzersiz kalmalıdır. Page başlığı ve bilgi varsayılan çeviriye göre okunduğundan, bu çeviriyi yeniden adlandırmak sayfanın kendisini yeniden adlandırır.

Yerelleştirilmiş kimlik ve SEO dışındaki alanlar, 422 ve onları blocked_fields olarak adlandıran unsupported_page_translation_fields koduyla reddedilir. Sayfa durumu, düzen ve blok içeriğinin kendi uç noktaları vardır.

Pages, site genelindeki varlıklara ek olarak kendi /site/... CSS ve JS dosyalarını yükleyebilir:

{type}, css veya js'dir. Listeleme geçerli herhangi bir token için geçerlidir; yazma uç noktaları, varsayılan sayfa oluşturma setinin parçası olmayan, özel isteğe bağlı page-assets.write yeteneğini gerektirir.

path sözleşmesi kasıtlı olarak daraltılmıştır ve bu API:

için güvenlik sınırıdır

• /site/ ile başlayan ve .css veya .js ile biten,
• harici URL'lerle eşleşen yerel bir yol olmalıdır (http://, https://), protokole bağlı (//), javascript: ve data: yolları reddedilir
• dizin geçişi, ters eğik çizgiler, sorgu dizeleri ve parçalar reddedildi

Bu uç nokta yalnızca mevcut bir dosyayı bir sayfaya ekler; asla dosya içeriğini yazmaz. Dosyayı API (PUT /webadmin/api/sites/{site}/assets/{type}, site-assets.write gerektirir) site varlıklarıyla veya yönetici kullanıcı arayüzünden yazın.

Desteklenen alanlar şunlardır: path (oluşturma sırasında gereklidir), sort_order, is_enabled ve — yalnızca JS varlıkları için — is_defer, is_async ve is_module. load_position, yönetici düzenleyiciyle eşleşen türden (CSS için head, JS için body_end) türetilmiştir. css/js türü güncelleme sırasında değiştirilemez; değiştirmek için silin ve yeniden ekleyin.

Sayfa bloğu topolojisi uç noktalarından farklı olarak, sayfa varlıkları yalnızca taslak değildir: yönetici Sayfa Varlıkları sekmesiyle eşleşecek şekilde herhangi bir sayfada değiştirilebilirler. Her yazma, bir sayfa revizyonunu yakalar.

Shared Slot blok ağaçlarının kendi topoloji uç noktaları vardır çünkü bunlar yuvanın atandığı her sayfada paylaşılır:

Blok ekleme POST /shared-slots/{sharedSlot}/blocks'de kalır ve tek bir bloğun güvenli içerik alanlarını düzenlemek PATCH /blocks/{block}'de kalır (zaten shared-slots.write ile Shared Slot kaynak bloklarını kabul eder). Yeni uç noktalar eksik topoloji işlemlerini ekliyor:

• PATCH .../blocks/reorder bir kardeş grubu yeniden numaralandırır; blocks dizisi, tek bir üst grup için her kardeş kimliğini istenen sırayla tam olarak bir kez içermelidir. shared-slots.write.
• DELETE .../blocks/{block} gerektirir, bir bloğu ve alt ağacını kaldırır ve deleted_blocks_count'yi döndürür.
• DELETE .../blocks, bir aracın yapabilmesi için yuvadaki her bloğu temizler. Shared Slot'yi temizleyin ve değiştirin; deleted_blocks_count.
• değerini döndürür. Her iki silme işlemi de shared-slots.write artı özel content.blocks.delete yeteneği gerektirir.

Sayfa bloğu düzenlemelerinden farklı olarak bunlar yalnızca taslak değildir: Shared Slots'de taslak sayfa kavramı yoktur. Bu nedenle önceden yayınlanmış bir Shared Slot bloğunun yeniden sıralanması veya silinmesi, atanan her sayfayı anında etkiler; bu nedenle, silme işlemi, yıkıcı content.blocks.delete özelliğinin arkasına alınır. Her yazma, yuvanın sayfa atamalarını yeniden oluşturur ve bir Shared Slot revizyonu yakalar, böylece değişiklikler geri alınabilir kalır.

Abranding, head, timezone ve public-theme'nin yanı sıra üç site alanı daha yazılabilir. Üçü de site-settings.write.

gerektirir

PATCH /webadmin/api/sites/{site}/seo, seo_title, seo_description ve seo_keywords'yi yazar: kendi sayfa çevirisi geçersiz kılınmadığında, genel bir sayfanın devraldığı site çapında geri dönüş meta verileri. Kısmi ve null bir alanı temizler. Sayfa düzeyindeki geçersiz kılmalar sayfa çevirisine aittir; yukarıdaki API Sayfa Çevirisine bakın.

PATCH /webadmin/api/sites/{site}/contact-recipient, contact_recipient_email yazar, iletişim formu gönderimlerinin postalandığı adrese gönderilir. Sistem alıcısına geri dönmek için boş bir değer gönderin. API aracılığıyla oluşturulan iletişim formu, bu ayarlanana kadar hiçbir işe yaramaz.

PUT /webadmin/api/sites/{site}/locales, sitenin locale_ids'den ayarlanan yerel ayarının yerini alır. Varsayılan yerel ayar her zaman tam olarak yönetici formunun koruduğu gibi korunur ve yerel ayarların öncelikle POST/PATCH /webadmin/api/locales aracılığıyla genel olarak etkinleştirilmesi gerekir. Sitenin etkinleştirmediği bir yerel ayar için sayfa çevirisi kaydedilemez; dolayısıyla bu, yeni bir yerel ayarın sitede kullanılabilir olmasını sağlayan uç noktadır.

Bu uç nokta, bir açıdan yönetici formundan daha katıdır: sitede hâlâ sayfa çevirileri bulunan bir yerel ayarı ayırmayı reddeder ve 422, yerel ayarı ve sayıyı adlandırır. Form, operatörün bunu bilerek yapmasına olanak tanır; gözetimsiz bir araç, içeriği sessizce yetim bırakır.

Etki alanı kayıtları, hangi ana bilgisayar adının hangi siteye çözümleneceğine karar verir, böylece tarayıcı yöneticisi bunları sistem düzeyinde erişimin arkasında tutar. API uç noktaları şunlardır:

• PATCH /webadmin/api/sites/{site}/seo
• PATCH /webadmin/api/sites/{site}/contact-recipient
• PUT /webadmin/api/sites/{site}/locales
• GET /webadmin/api/sites/{site}/domains gerektirir content.read
• POST /webadmin/api/sites/{site}/domains gerektirir domains.write
• PUT /webadmin/api/sites/{site}/domains/{domain}, domains.write
• gerektirir
• POST /webadmin/api/sites/{site}/domains/{domain}/primary, domains.write
• gerektirir
• DELETE /webadmin/api/sites/{site}/domains/{domain}, yıkıcı olanı gerektirir domains.delete
• GET /webadmin/api/domains/{domain}/status, content.read

gerektirir

Bu uç noktalar daha önce yalnızca /admin-api öneki altında yaşıyordu ve belirteç geçerliliğinin ötesinde hiçbir şeyi kontrol etmiyordu; dolayısıyla herhangi bir belirteç, bir alan adını ekleyebilir veya kaldırabilirdi. Artık API'nin geri kalanıyla birlikte /webadmin/api'nin altında yer alıyorlar ve her rota bir yetenek taşıyor. /admin-api öneki, aynı yetenek gereksinimleri ve ekstra bir rota olan GET /admin-api/sites ile mevcut sağlama araçları için çalışmaya devam eder; yeni entegrasyonlar, yolları aynı zamanda eski önekin hiçbir zaman sahip olmadığı CSRF muafiyetinin kapsamına giren /webadmin/api'yi kullanmalıdır.

PATCH /webadmin/api/shared-slots/{sharedSlot}, shared-slots.write gerektirir ve blokları yerine Shared Slot'nin kendisini değiştirir: label, handle, slot, layout ve is_active. Yalnızca mevcut alanlar yazılır. Tanıtıcılar site başına benzersiz kalır, yuva adı yayınlanmış bir yuva türüne çözümlenmelidir ve Shared Slot kaynak sayfası ve atamaları daha sonra tam olarak tarayıcı yöneticisinin onları yeniden oluşturduğu gibi yeniden oluşturulur. Bir meta veri veya durum değişikliği, bir Shared Slot revizyonunu yakalar.

Bir Shared Slot'yi başka bir siteye taşımak burada desteklenmez ve 422 ve unsupported_shared_slot_fields koduyla reddedilir; bu aynı zamanda bu kümenin dışındaki diğer alanları da kapsar. Siteler arası hareketler, diğer site aktarım işlemleriyle birlikte tarayıcı yöneticisinde kalır.

DELETE /webadmin/api/shared-slots/{sharedSlot}, yıkıcı shared-slots.delete yeteneğini gerektirir ve tarayıcı yöneticisiyle aynı korumayı uygular: hala herhangi bir sayfa yuvası tarafından başvurulan bir Shared Slot asla silinmez. 422 yanıtı, shared_slot_in_use kodunu ve referans sayfa yuvalarını adlandıran bir usage dizisini taşır, böylece bir araç bunları ilk önce PUT /webadmin/api/pages/{page}/slots/{slot}/source ile ayırabilir. Shared Slot referans sütunları henüz taşınmamışsa uç nokta, tahmin etmek yerine shared_slots_not_ready ile 409 değerini döndürür.

Medya Kitaplığı API, geniş içerik izinlerinden kasıtlı olarak ayrılmıştır, böylece yapay zeka/operatör araçlarına ilgisiz yazma güçleri almadan medya keşfi veya meta veri temizleme verilebilmektedir.

Yetenekler:

• media.read: mevcut CMS Medya Kitaplığı kayıtlarını listeleyin ve inceleyin.
• media.upload: dosyaları Medya Kitaplığına yükleyin.
• media.write: mevcut medya kayıtlarındaki güvenli meta verileri güncelleyin.
• media.replace: medya kimliğini korurken mevcut bir medya dosyasını değiştirin.
• media.move: medyayı aralarında taşıyın klasörlerini silin veya klasörünü temizleyin.
• media.delete: kullanılmayan medyayı yönetici paneliyle aynı kullanım korumasıyla silin.

Faz 1 kapsamı:

GET /webadmin/api/media, kimlik, tür, başlık, dosya adı, orijinal ad, mime türü, görünürlük, mevcut olduğunda genel URL, alternatif metin, boyutlar, önizlenebilirlik ve kompakt meta veri etiketi gibi güvenli alanlarla mevcut medya kayıtlarını döndürür. media.read gerektirir. Eski API belirteçlerinden geçiş sırasında, mevcut sayfa oluşturma entegrasyonlarının çalışmaya devam etmesi için content.read salt okunur medya keşfi için de kabul edilebilir.

GET /webadmin/api/media/folders, Ortam Kitaplığı klasörlerini ortam sayılarıyla birlikte listeler ve POST /webadmin/api/media/folders, media.write gerektirir ve isteğe bağlı slug ve parent_id ile name'den bir tane oluşturur. Aynı üst öğe altında zaten mevcut olan bir ad, 422 ve media_folder_exists koduyla reddedilir ve yanıt, mevcut klasörü taşır, böylece yeniden deneme aracı, kopyalar oluşturmak yerine onu yeniden kullanır. Dosya, folder_id içeren bir klasöre yüklenir; POST /webadmin/api/media/{media}/move.

ile mevcut medyayı taşıyın

POST /webadmin/api/media, media.upload gerektirir ve normal CMS Medya Kitaplığına multipart/form-data yüklemelerini kabul eder. Yüklenen dosya normal bir media satırı haline gelir ve tarayıcı yöneticisi Medya ekranında ve medya seçicilerde görünür. Yükleme doğrulaması, tarayıcı yöneticisi Medya Kitaplığı'nın izin verdiği dosya türlerini yansıtır: yaygın resimler, videolar, PDF'ler, Office belgeleri, metin/CSV/RTF ve ZIP dosyaları.

Desteklenen meta veri alanları folder_id, title, alt_text, caption ve description'dir. Uç nokta, oluşturulan medya nesnesini, mevcut olduğunda kimliği ve genel URL'siyle birlikte döndürür.

PATCH /webadmin/api/media/{media}, media.write gerektirir ve yalnızca güvenli tanımlayıcı meta verileri günceller:

• title
• alt_text
• caption
• description

POST /webadmin/api/media/{media}/replace, media.replace gerektirir ve ortam kimliğini ve mevcut referansları korurken depolanan ikili dosyayı değiştirir. Değiştirilen dosyanın, görüntüden görüntüye veya belgeden belgeye gibi mevcut kayıtla aynı ortam türüne çözümlenmesi gerekir. Yanıt, mevcut kullanım ayrıntılarını içerir; böylece araçlar, değişikliğin blokları, site markalamasını veya sayfa SEO'yu etkileyip etkilemediğini görebilir.

POST /webadmin/api/media/{media}/move, media.move gerektirir ve klasör atamasını temizlemek için null dahil folder_id'yi kabul eder.

DELETE /webadmin/api/media/{media}, media.delete gerektirir ve tarayıcı yöneticisiyle aynı kullanım korumasını kullanır. Bloklar, galeriler, ekler, site markalaması veya sayfa SEO'su tarafından referans verilen medya silinmez; API, bunun yerine kullanım ayrıntılarını içeren 422'yi döndürür.

Bu API açıkça şunu desteklemez:

• disk, yol, dosya adı, mime türü, tür, görünürlük, boyut, boyutlar, yükleyici veya kullanım ilişkilerini doğrudan değiştirme
• uzak medya URL'lerini alma veya içe aktarma

Bu sınır, yapay zeka/operatör araçlarının yalnızca ihtiyaç duydukları medya güçlerini almasına olanak tanır. Örneğin, bir sayfa oluşturma belirteci, mevcut dosyaları silmeden veya değiştirmeden medyayı okuyabilir ve yükleyebilir; güvenilir bir bakım belirteci ise media.replace veya media.delete'ye açıkça verilebilir.

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

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

Page Çevirisi path standart genel URL'dir. Yeni planlar /contact, /features, /games/fruit-train veya /docs/internal-content-api gibi yolları kullanmalıdır; /p/... yalnızca eski sürümlerle uyumludur. Eğik çizgi taşıyan yollar bölüm bölüm normalleştirilir, böylece /docs/internal-content-api/, /docs/internal-content-api olur ve docsinternal-content-api'ye daraltılmaz. CMS, kısa sayfa bilgisini son yol bölümünden türetir, böylece /games/fruit-train, fruit-train bilgisini ve /games/fruit-train yolunu saklar. /webadmin, /webadmin/api, /cms, /search, /search.json, /contact-messages, /install gibi ayrılmış rota alanları ve ana bilgisayar kimlik doğrulama rotaları genel sayfa yolları olarak oluşturulamaz.

Eörnek:

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

Yayınlanan sayfalar doğrudan değiştirilemez. Kaynak bağlantılı doküman sayfaları veya içerik değişiklikleri hazırlanırken herkese açık kalması gereken diğer yayındaki sayfalar için aşamalı güncelleme modlarını kullanın:

create_staged_update_for_published_page, yalnızca söz konusu kaynak sayfada halihazırda etkin bir taslak aşamalı güncelleme bulunmadığında, yayınlanan kaynak sayfadan bir taslak hazırlama sayfası oluşturur. Aynı kaynak sayfa için oluşturma çağrısını tekrarlamak, başka bir teknik sayfa oluşturmak yerine data.reused_staged_update=true ile mevcut etkin aşamalı taslağı döndürür. Kaynak sayfa mevcut genel yolunda yayınlanmaya devam eder. Aşamalı sayfa, kaynak sayfa kimliği, kaynak yolu, kaynak güncellenmiş zaman damgası, yaşam döngüsü durumu ve yönetilen yuvalarla birlikte settings.staged_update meta verilerini depolar. /staged-updates/page-123/update-456 gibi dahili bir taslak yolu kullanır, bu nedenle kaynak kanonik yoluyla çakışmaz ve herkese açık olarak yönlendirilmez. Normal yönetici önizleme URL'si /webadmin/pages/{page}/preview, kimliği doğrulanmış yönetici oturumları için hazırlanmış sayfayı veya content.read.

ile CMS API Taşıyıcı belirteçlerini oluşturabilir.

replace_staged_page_update, taslak değiştirme kurallarını aşamalı taslak sayfasına göre yeniden kullanır. Aşamalı bir taslak oluşturulduktan sonraki her revizyon için bunu kullanın. Yalnızca sayfaya ait yuvaların yerini alır ve Shared Slot destekli yuvaları reddeder.

promote_staged_page_update, aşamalı sayfaya ait alan içeriğini bir işlemde yayınlanan kaynak sayfaya geri uygular. İzin verilenler listesine eklenen bir source_sync güncellemesi sağlanmadığı sürece kaynak sayfa yolunu, durumu, düzeni, Shared Slot atamalarını ve sayfa ayarlarını korur. Tanıtılan sayfaya ait bloklar published olarak yazılır, böylece genel sayfa tanıtılan içeriği hemen yansıtır. Shared Slot içeriği hiçbir zaman basamaklandırılmaz. Kaynak sayfanın tanıtım öncesi/sonrası güvenlik versiyonları yakalandıktan sonra, teknik olarak hazırlanmış sayfa aynı işlemde silinir; başarısız bir terfi bu nedenle taslağı düzeltmeye açık bırakır. Tanıtım, normal content.apply rota yeteneği ve gelişmiş content.publish yeteneği gerektirir.

Etkin aşamalı taslağı terk etmek için DELETE /webadmin/api/pages/{staged_page}/staged-update kullanılır. Bu dar kapsamlı atma uç noktası content.apply gerektirir, yalnızca etkin aşamalı güncelleme meta verileri içeren bir taslak sayfasını kabul eder ve yayınlanan kaynak sayfayı veya kayıtlı sürümlerini hiçbir zaman değiştirmez. Bir sayfa oluşturma aracına yalnızca kendi teknik taslağını temizlemek için geniş pages.delete yeteneği vermekten kaçınır.

Normalleştirilmiş bir uygulama planı doğrulamayı geçerse ancak işlem yazmaları sırasında başarısız olursa, API, ok=false ile JSON normal doğrulamasını ve plan.apply'de bir hatayı döndürür. Ayrıntılı istisna uygulama günlüklerine kaydedilir; API yanıtları genel olarak güvenli kalır ve yığın izlemeleri, veritabanı dahili bilgilerini, belirteçleri veya yerel yolları içermez.

Örnek aşamalı iş akışı:

Daha sonra hazırlanan içeriği değiştirin:

Önizleme ve açık onaydan sonra tanıtım yapın:

Bu iş akışı için yeni şema tablosu gerekmez; etkin aşamalı yaşam döngüsü meta verileri mevcut Sayfa settings JSON sütununu kullanır. Kaynak sayfa sürümleri kurtarma takibi sağladığından tanıtılan teknik sayfalar saklanmaz.

Tanıtılan aşamalı sayfaları arşivleyen bir sürümden yükseltme yapan kurulumlar, bu eski kayıtları bir kez önizleyebilir ve kaldırabilir:

Komut yalnızca hazırlanmış meta verilerinde açıkça type=published_page_update ve state=promoted yazan arşivlenmiş sayfaları seçer. Etkin taslaklar ve sıradan arşivlenmiş sayfalar asla aday değildir.

İç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:

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.

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

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

Kurallar:

• omited include_page_owned_blocks, false
• gibi davranır
• include_page_owned_blocks: false yalnızca sayfa kaydını yayınlar ve taslak veya inceleme içi blokları değiştirmeden bırakır
• include_page_owned_blocks: true, iç içe alt bloklar da dahil olmak üzere sayfanın paylaşılmayan sayfa yuvalarına ait taslak ve inceleme bloklarını yayınlar
• zaten yayınlanmış bloklar değişmeden kalır
• Shared Slot destekli alanlar yanıtta hariç tutuldu ve rapor edildi
• desteklenmeyen Shared Slot publish_shared_slots, include_shared_slot_blocks veya shared_slot_cascade gibi basamaklı alanlar JSON'yi döndürür 422
• yanıt, sayfa kimliğini/durum/yol meta verilerini, sayfaya ait blokların dahil edilip edilmediğini, yayınlanan sayıyı, hariç tutulan Shared 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ı Shared Slot hariç tutma kuralını kullanır.

POST /webadmin/api/pages/{page}/archive sayfayı genel siteden çıkarır: arşivlenen sayfalar ziyaretçilere 404 döndürür ve sayfa bağlantılı menü öğeleri genel menülerde görüntülenmeyi durdurur. Aynı content.publish özelliğini kullanır ve yönetici iş akışı kurallarını yansıtır: in_review ve published'den izin verilir, bir taslak sayfası JSON 422'yi döndürür, arşivlenmiş bir sayfayı yeniden arşivlemek işlem gerektirmeyen bir başarıdır ve aşamalı güncelleme sayfaları reddedilir (bunun yerine bunları tanıtın veya silin). Yanıt, sayfa meta verilerini, from_status'yi ve yakalanan sayfa revizyon kimliğini içerir. Sayfanın tekrar yayınlanması arşivi tersine çevirir.

I/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'yi yalnızca kullanıcı o sayfa için yayınlanmamış sayfaya ait tüm blokların yayınlanmasını açıkça onayladığında kullanın. Shared Slot içeriği ayrı olarak incelenmeli ve yayınlanmalıdır.

GET /webadmin/api/content-contract, güvenilir yapay zeka/operatör araçları için salt okunur bir keşif uç noktasıdır. API önekini, URL'leri doğrulama/uygulama URL'lerini, yönetici önizleme URL şablonunu, güvenlik işaretlerini, keşif URL'lerini, önerilen sayfa oluşturma modellerini, makine tarafından okunabilir bir tasarım yönü sözleşmesini ve arındırılmış blok sözleşme meta verilerini döndürür.

Bir blok ağacı seçmeden önce, araçlar design_direction'yi okumalı, character, density, typography, geometry, imagery'nin her biri için bir değer seçmelidir, corners, contrast ve framing ve kompozisyon haritasının bu seçimleri nasıl uyguladığını açıklayın. Bu, gizli bir içerik deposundan ziyade bir planlama sözleşmesidir: sonuç, yerel blok ayarları, genel tema belirteçleri ve kararlı site CSS aracılığıyla ifade edilir. Oluşturma politikası, yeni API planları için Sütunları varsayılan olarak düz hale getirir, Kartların etkin olmasını sağlar ve her Kart koleksiyonu için bir içerik sınırı/eylem gerekçesi gerektirir. Üç kısa madde içeren bir kaynak böyle bir gerekçe olamaz.

framing, kalıcı sayfa verileri değil, bir planlama boyutudur. İçeriğe ve bağlama göre open, restrained, framed veya dense-ui'yi seçin. Kart veya çerçeveli paneli yalnızca bir bölümü düzenlemek için kullanmayın. Çerçeveleme anlamsal bağımsızlığı, etkileşimi veya varlık sınırlarını iletmelidir. Kahraman dış kapsayıcılar, özellik/ilke grupları, bölüm sarmalayıcılar, gezinme/alt bilgi sütunları, CTA bantları, dekoratif istatistikler ve içerik bölmeleri varsayılan olarak çerçevesizdir. Boşlukları, tipografi hiyerarşisini, asimetrik düzeni, bölücüleri, ton değişikliklerini, geniş bölümleri, hizalamayı, ofset/örtüşmeyi ve ölçülü kuralları tercih edin. Gerekli çerçeveli yüzey denetimi, varlık dışı çerçeveli her yüzeyi doğrulamalıdır; “bölümü görsel olarak ayırmak” yeterli değildir.

Bitişikteki design_fixtures bölümü, standart yerel blok ağaçlarını, uyumlu tasarım yönergelerini, beklenen genel kancaları, anti-örüntüleri ve deterministik masaüstü/mobil yakalama boyutlarını yayınlar. Durumu, kaynak destekli işleme sözleşmesini insan onaylı ekran görüntülerinden ayırır. Araçlar bir kompozisyon referansı olarak bir fikstür ağacı kullanabilir ancak kayıt defteri render_contract_ready_capture_pending rapor ederken görsel onay talep etmemelidir. Kullanılabilir fikstür sözleşmelerini keşif yanıtındaki design_fixtures alanında inceleyin.

Uç nokta genel CMS ürün davranışıdır. Kuruluma özel gizli diziler, belirteç değerleri, ham Blade içerikleri, mutlak dosya sistemi yolları, özel sunucu yolları veya siteye özel talimatlar döndürmemelidir. Blok sözleşme satırları; tanıtıcı/bilgi, etiket, kategori, durum, kapsayıcı ve alt destek, çevrilebilir alanlar, paylaşılan ayarlar alanları ve genel oluşturucu kök davranışını içerebilir.

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

Block sözleşmeleri, settings.icon_slug, settings.icon_tone, settings.icon_size, settings.badge_tone ve çevrilmiş eyebrow/badge_label kopyası dahil olmak üzere isteğe bağlı genel simge ve rozet alanlarını açığa çıkarabilir. Araçlar, simge bilgi notlarını serbest metin yerine katalog destekli seçimler olarak ele almalıdır; genel işleme, bilinmeyen veya etkin olmayan simgeleri atlar ve yalnızca etkin WebBlocks UI katalog satırları için güvenli wb-icon wb-icon-{slug} sınıfları yayar. settings.icon_tone, yerele ait kopya değil, paylaşılan genel bir görsel ton ayarıdır ve yalnızca default, soft, brand, accent, highlight, bold ve quiet'yi kabul eder; settings.icon_size, default, sm, lg veya xl'yi kabul eder ve eşleşen WebBlocks UI boyut sınıfıyla eşleşir. info, success, warning ve danger, rozetler, uyarılar, doğrulama ve geri bildirim için anlamsal durum tonları olarak kalır. Bilinmeyen simge tonları veya boyutları, içerik planı doğrulaması sırasında reddedilir veya güvenli bir geri dönüş olarak genel oluşturma tarafından göz ardı edilir. Rozet tonu yalnızca bloğun çevrilmiş rozet etiketi kopyasına da sahip olması durumunda ortaya çıkar.

GET /webadmin/api/icon-catalog?context=content, API istemcilerinin genel içerik bloklarına atayabileceği etkin güvenli simge bilgi dosyalarını döndürür. Gezinme öğesi simgesi seçeneklerinde gezinme etiketli önerileri ilk sırada sıralamak için context=navigation'yi kullanın; bağlam izin verilenler listesinden ziyade bir ipucu olduğundan, her iki bağlam da hâlâ tüm etkin simgeleri döndürüyor. API araçları, settings.icon_slug göndermeden veya icon değerlerini gezinmeden önce bu uç noktayı okumalı ve WebBlocks UI bildiriminden simge adlarını tahmin etmemelidir.

contact_form sözleşmesi ek güvenli form meta verileri içerir: ayarlar şeması, çevrilmiş alanlar, genel POST /contact-messages gönderim uç noktası, gerekli CSRF tarayıcı davranışı, sunucu doğrulama kuralları, CMS'ye ait gizli oluşturulan anti-spam kontrol alanı, genel kontrol alanı başarı davranışı, spam sınıflandırma/karantina notları, bildirimden önce depolama davranışı, alıcı geri dönüşü sipariş, güvenli bildirim hatası kaydı ve /webadmin/contact-messages inceleme davranışı. Kontrol alanı oluşturucu tarafından oluşturulur, normal ziyaretçi girişinin parçası değildir ve API veya AI/operatör araçları tarafından manuel olarak oluşturulmamalıdır. İletişim sayfası araçları Güvenilir HTML, ham form işaretlemesi veya mailto: formları yerine bu yerel bloğu kullanmalıdır. Eski website alanı artık genel İletişim Formu sözleşmesi değildir.

İnsan tarafından okunabilen Yapay Zeka Sayfası Oluşturma Kılavuzu, vendor/fklavyenet/webblocks-cms/docs/ai-page-building-guide.md.

adresinde yerel paket kurulumlarıyla gönderilir

• 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/locale-options
• POST /webadmin/api/locales
• PATCH /webadmin/api/locales/{locale}
• GET /webadmin/api/page-layouts
• GET /webadmin/api/block-types
• GET /webadmin/api/icon-catalog
• GET /webadmin/api/content-contract

• GET /webadmin/api/pages
• GET /webadmin/api/pages/{page}
• GET /webadmin/api/pages/{page}/render
• GET /webadmin/api/pages/{page}/translations
• POST /webadmin/api/pages/{page}/translations/{locale}
• PATCH /webadmin/api/pages/{page}/translations/{translation}
• POST /webadmin/api/pages/{page}/sync-layout-slots
• PATCH /webadmin/api/pages/{page}/layout
• POST /webadmin/api/pages/{page}/slots/{slot}/shared-slot
• PUT /webadmin/api/pages/{page}/slots/{slot}/source

• 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
• PATCH /webadmin/api/navigation-menus/{navigationMenu}/items/{item}
• PATCH /webadmin/api/navigation-menus/{navigationMenu}/items/reorder
• DELETE /webadmin/api/navigation-menus/{navigationMenu}/items/{item}

Navigasyon menüleri mevcut CMS navigation_items.menu_key modelini kullanır. Aşama 2A, primary, footer, mobile, legal ve docs gibi gönderilen CMS menü tutamaçlarını destekler; ayrı bir menü tablosu eklemez. Gezinme menüsü oluşturmak, isteğe bağlı başlangıç ​​öğeleriyle güvenli, site kapsamlı bir menü grubu oluşturmak olarak değerlendirilir. Zaten öğelerin bulunduğu bir sitenin/menünün üzerine yazmayı reddediyor.

Gezinme öğesi oluşturma, güncelleme, görünürlük değişiklikleri ve yeniden sıralama navigation.write gerektirir. Silme, açık yıkıcı navigation.delete yeteneğini gerektirir. Öğe güncellemeleri label/title, url, link_type, page_id, target, visibility, sort_order/position'yi destekler, parent_id ve icon; burada bu alanlar seçilen bağlantı türü için geçerlidir. Güncellemeler kısmidir: yükte bulunmayan alanlar, depolanan değerlerini yeniden doğrulamaya gerek kalmadan korur, böylece eski satırlar (ağaç düzenleyici öncesi sıralama düzeni 0, sayfa türü bir ebeveynin altına yerleştirilmiş bir alt öğe) güncellenebilir kalır; kurallar bir isteğin gerçekte gönderdiği değerler için geçerlidir.

Item güncellemeleri ayrıca blok çeviri yazmalarını yansıtan isteğe bağlı bir locale anahtarını (öğenin sitesi için etkinleştirilmiş bir yerel ayar kodu) kabul eder. locale olmadan veya site varsayılan yerel ayarıyla, label/title, kurallı varsayılan yerel ayar başlığını yazar. Varsayılan olmayan bir locale ile label/title değeri, söz konusu öğe için yerel ayar anahtarlı bir çeviri satırı olarak depolanır ve standart başlığa dokunulmadan kalır; aynı istekteki diğer alanlar (görünürlük, konum vb.) paylaşılmaya devam eder ve öğenin kendisine uygulanır. Genel oluşturma, istenen yerel ayar için gezinme başlığını seçer ve çeviri satırı bulunmadığında standart varsayılan yerel ayar başlığına geri döner. Öğe okuma verileri, yerel ayar başına depolanan başlıkları, yerel ayar koduyla anahtarlanan bir title_translations haritası olarak gösterir. Yeniden sıralama verileri, seçilen sitedeki/menüdeki her öğeyi tam olarak bir kez içermelidir. Sil, hâlâ alt öğeleri olan üst öğeleri reddeder, bu nedenle araçların basamaklı işlemlere güvenmek yerine önce alt öğeleri taşıması veya silmesi gerekir.

Gezinme öğesi URL'leri, /, /about, /contact ve /#platform gibi dahili yollar veya güvenli http/https URL'leri olabilir. Aynı sayfadaki bağlantılar için yol artı parça kullanın; #platform gibi yalnızca ham parça değerleri gezinme URL'leri değildir. API, javascript:, data:, protokole bağlı URL'leri, geçişi, hatalı biçimlendirilmiş URL'leri, desteklenmeyen hedefleri ve boş etiketleri reddeder. Gezinme uç noktaları sayfa oluşturmaz, sayfa yayınlamaz, siteleri taramaz, uzak URL'leri getirmez veya alt öğeleri basamaklı olarak silmez.

• GET /webadmin/api/shared-slots
• GET /webadmin/api/shared-slots/{sharedSlot}
• PATCH /webadmin/api/shared-slots/{sharedSlot}
• DELETE /webadmin/api/shared-slots/{sharedSlot}
• POST /webadmin/api/shared-slots
• POST /webadmin/api/shared-slots/{sharedSlot}/blocks
• POST /webadmin/api/shared-slots/{sharedSlot}/publish-blocks

Shared Slot oluşturma, site kapsamlıdır ve aynı site için yinelenen tanıtıcıları reddeder. Shared Slot blokları, sayfaya ait bloklar tarafından kullanılan aynı blok yükü yazıcısını yeniden kullanır, böylece yerele ait kopya çeviri satırlarında kalır ve paylaşılan ayarlar blok kayıt/ayarlar yolunda kalır. Shared Slot blok ekleme istekleri, üst öğe istenen alt türü kabul ettiğinde aynı Shared Slot kaynak ağacındaki mevcut bir bloğun altına bir blok eklemek için parent_id veya parent_block_id'yi içerebilir. Shared Slot blokları taslak içerik olarak oluşturulur ve herkese açık olarak oluşturulmadan önce shared-slots.write artı content.publish ile açık POST /webadmin/api/shared-slots/{sharedSlot}/publish-blocks gerektirir. Medyayı içe aktarma ve medya ataması bu aşamanın dışında kalır.

shared-slot uç noktası, mevcut bir uyumlu aynı site aktif Shared Slot'yi mevcut bir sayfa yuvasına atar. Sayfayı yayınlamıyor. Siteler arası, etkin olmayan ve uyumsuz Shared Slots'yi reddeder. Ayrıca, Aşama 2A bu blokları otomatik olarak silmediğinden veya değiştirmediğinden, hâlâ sayfaya ait blokları olan bir yuvayı değiştirmeyi de reddeder.

PUT .../source, yuvanın içerik kaynağını yazar ve çıkış yoludur: source_type, page, shared_slot veya disabled'yi kabul eder. content.apply gerektirir ve shared_slot ayrıca shared-slots.write'yi ve yetki verdiği atama uç noktasıyla aynı uyumluluk kurallarını gerektirir. Ayırma, shared_slot_id'yi temizler ve sayfaya ait bloklara dokunulmaz; böylece page bunları yeniden işler ve disabled, içinde hiçbir şey olmadan yuva sarmalayıcıyı tutar. Bu uç nokta mevcut olmadan önce API, bir Shared Slot referansı oluşturabiliyordu ve bunu kaldırmanın bir yolu yoktu; tek çıkış, oturum kimlik doğrulamalı yönetici ekranıydı.

Sayfa düzeni header gibi bir yuva içeriyorsa ancak sayfa kaydı bu Sayfa Yuvası mevcut olmadan önce oluşturulmuşsa, önce POST /webadmin/api/pages/{page}/sync-layout-slots'yi çağırın. Yuva senkronizasyonu önemsizdir ve yalnızca seçilen Sayfa Düzeninde eksik Sayfa Yuvaları oluşturur; mevcut yuvaları, blokları, devre dışı bırakılmış durumları, Shared Slot atamalarını, çevirileri veya revizyonları asla silmez. Yeni bir Shared Slot başlığı için genel çıktıyı beklemeden önce Shared Slot bloklarını açıkça yayınlayın.

Mevcut bir sayfanın Sayfa Düzenini (public_shell) yazar. Yönetici düzenleme formu bunu her zaman değiştirebilir; API önceden bunu yalnızca sayfa oluştururken ayarlayabiliyordu. content.apply bunu kapsar. layout (veya handle), GET /webadmin/api/page-layouts'nin aktif tanıtıcılarından biri olmalıdır; eski dashboard takma adı hala docs'ye normalleştirilir. PageController::update()'nin kendi sözleşmesiyle eşleşir: Düz düzen değişikliğinde Sayfa Yuvalarını değiştirmez, dolayısıyla bu uç nokta da değiştirmez. Yeni düzen sayfanın henüz sahip olmadığı alanları tanımlıyorsa sync-layout-slots'yi ayrıca arayın.

Bu uç nokta yalnızca genel oluşturma tarafından kullanılan güvenli site genel tema ön ayarını günceller. public_theme_preset veya theme'yi canvas, atlas, pulse, prism, graphite veya horizon gibi desteklenen Site::PUBLIC_THEME_PRESETS değerlerinden biriyle gönderin. API keşfi, yanlış data-wb-public-theme ön ayarına sahip bir site oluşturmayı gösterdiğinde bunu kullanın; ön ayarı içerik bloklarıyla geçersiz kılmaya çalışmayın.

PATCH /webadmin/api/sites/{site}/branding, site-settings.write gerektirir ve Sites -> Edit Site -> Branding:

'de de görülebilen güvenli genel site markalama alanlarını günceller

• display_name
• tagline
• favicon_media_id
• social_image_media_id
• Medya değişimi, Medya kimliğini ve editoryal referansları korur, eski görüntü dönüşümlerini temizler ve değişimden gelecekteki varyantları türetir ikili.

Favicon ve sosyal resim alanları, CMS Medya Kitaplığı'ndaki resim kayıtlarına referans vermelidir ve null, seçilen medyayı temizler. Sonucun yönetici tarafından düzenlenebilir kalması için genel site favicon değişiklikleri bu uç noktayı kullanmalıdır. /cms/brand/*'nin üzerine yazmayın; bu dosyalar site düzeyinde genel markalama değil, CMS ürün/yönetici kabuk varlıklarıdır.

PATCH /webadmin/api/sites/{site}/timezonegerekliliklersite-settings.writeve bir sitenin kendi saat dilimini (örneğin, standart bir IANA tanımlayıcısı) belirler.Europe/Berlin. Bir eklentinin rezervasyon kullanılabilirlik pencereleri gibi o site için yerel duvar saati süresini çözümleyen her şey bu değere göre yorumlanır. Boş göndertimezonekurulum genelindeki sistem saat dilimine geri dönmek içinAdmin -> System Settings.

GET /webadmin/api/sites/{site}/assets/{css|js}, site-assets.read gerektirir ve standart fiziksel site düzeyinde geçersiz kılma dosyasını okur. relative_path, public_path, exists, contents, checksum, size, updated_at, readiness, guidance değerini döndürür ve CSS analysis, sunucunun mutlak yolunu açığa çıkarmadan. readiness nesnesi, site dizininin, varlık dizininin ve dosyanın CMS'nin varlığı oluşturması veya güncellemesi için yeterince yazılabilir olup olmadığını bildirir. guidance nesnesi, yapay zeka/operatör araçlarına CSS belirtecini öncelikli, moda duyarlı ve yerel bloğu öncelikli tutmasını söyler. CSS için asset.analysis.mode_awareness, status'yi, uyarı mesajlarını, algılanan desen önleme anahtarlarını, gerçek renk sayımı gibi sinyalleri ve önerilen --wb-public-* belirteçlerini raporlar. PUT /webadmin/api/sites/{site}/assets/{css|js}, site-assets.write gerektirir ve şunu kabul eder:

• contents
• expected_checksum

Yazma uç noktası, Sites -> Edit Site -> Assets ile aynı fiziksel dosya deposunu kullanır. Yalnızca public/site/{site_handle}/css/site.css veya public/site/{site_handle}/js/site.js yazar, ilk kayıtta eksik dizinler oluşturur, eski expected_checksum değerlerini reddeder ve mevcut değiştirilmiş bir dosyayı değiştirmeden önce üzerine yazma öncesi revizyon anlık görüntüsünü saklar. Veritabanı geri dönüş yolu ve rastgele /site/... yol yazıcısı yoktur. Barındırma izinleri dizin oluşturmayı veya dosya yazma işlemlerini engelliyorsa uç nokta, HTML sunucu hatası yerine errors.0.path = asset.write ve geçerli hazırlık meta verilerini içeren JSON 422'yi döndürür.

CSS yazmaları için, özel seçiciler eklemeden önce yerel blok yapısını/ayarlarını, Medya Kitaplığı arka plan alanlarını, genel tema belirteçlerini ve devralınan WebBlocks UI bileşen stillerini kullanın. Özel renkler kaçınılmazsa, genel sayfaların Açık/Koyu/Otomatik modda tutarlı kalması için, etkin mod seçicilere veya genel tema belirteçlerine bağlı açık ve koyu değerlere sahip semantik özel özellikler tanımlayın. Genel tema belirteçleri tasarımı ifade edebildiğinde sayfa çapında sabit kodlu açık arka planlardan, koyu metinlerden, beyaz kartlardan veya tek seferlik karanlık mod paletlerinden kaçının. PUT, bazı marka sistemleri kasıtlı özel renklere ihtiyaç duyduğundan mod farkındalığı uyarılarını reddetmez, ancak araçların, asset.analysis.mode_awareness.status = warning'yi, bir geçişi veya yeni site kurulumunu tamamlamayı düşünmeden önce inceleme, raporlama veya düzeltme çalışması olarak ele alması gerekir.

Yorumlar analizden önce çıkarılır: onardığı kuraldan alıntı yaparak kendisini belgeleyen bir stil sayfası, alıntılanan rengi kendisinden biri olarak bildirmez ve yalnızca bir yorumda adı verilen karanlık mod kapsamı mevcut olarak sayılmaz.

anti_patterns denetimleri sayfa çapında boyamayla ilgilidir, dolayısıyla her biri kendi belirtecinin seçicinin son bileşiği olmasını ve adın bittiği yerde bitmesini gerektirir: body { background: #fff } bildirilir, body .promo { background: #fff } ve .wb-public-body { ... } bildirilmez ve .wb-card-title bildirilir .wb-card olarak okunmadı. Bir öğeyi boyayan kural, sayfa çapında bir anti-desen olarak rapor edilmek yerine gerçek renk sinyallerine bırakılır.

asset.analysis.mode_awareness, bir CSS linter değil, kasıtlı olarak buluşsal bir sözleşmedir. pass veya warning, warnings, algılanan anti_patterns, gerçek renk bildirimleri gibi basit signals, uses_public_theme_tokens ve has_dark_mode_scope'nin yanı sıra önerilen --wb-public-* belirteç rollerini bildirir. Araçlar, olası karışık mod regresyonlarını erken yakalamak için bu sinyali kullanmalı ve nihai tasarım eşitliği için yine de görsel KG'ye güvenmelidir.

Uygulama kodu bir sitenin genel site.css veya site.js'siyle birleştirilmemelidir. Kayıtlı bir Embedded Application, site kapsamlı genel dizini altında fiziksel CSS, JavaScript ve bir yönetilen index.html girişine sahip olabilir:

CSS ve JavaScript, /site/{site_handle}/applications/{application_handle}/{type}/{filename} deterministik genel yolunu kullanır. HTML türü yalnızca index.html'yi kabul eder, bunu uygulama kökünde saklar ve ana bilgisayar tarafından seçilen kararlı genel yol /webblocks-applications/{application_handle}/index.html'yi döndürür. Bu yönetilen girişin yazılması, tanımı iframe moduna geçirir ve bu URL'yi etkinleştirir. GET, PUT ve DELETE, sırasıyla applications.read, applications.write ve applications.delete gerektirir. Dosya adları yalnızca temel adlardır ve seçilen .css, .js veya .html uzantısıyla bitmelidir. HTML, index.html dışında hiçbir dosya adını kabul etmez; geçiş, iç içe geçmiş yollar, diğer dosya türleri ve uzak URL'ler reddedilir.

PUT, contents ve expected_checksum'yi kabul eder. null'yi yalnızca eksik bir dosya oluştururken gönderin; Önce mevcut bir dosyayı okuyun ve değiştirirken sağlama toplamını gönderin. Değiştirmeler ve silmeler revizyon kopyalarını korur. Embedded Application tanımı hala varlığın genel yoluna başvururken silme işlemi reddedilir. Bir varlığı yazdıktan sonra, döndürülen public_path'yi css_assets veya js_assets'de kullanın; Uygulama Bloğu daha sonra onu yalnızca uygulamanın yerleştirildiği yere yükler.

Complete uygulamaları, dosyaları tek tek yazmak yerine paket uç noktasını kullanmalıdır. Bir package ZIP alanına sahip applications.write ve multipart/form-data gerektirir (maksimum yükleme boyutu 50 MB). İlk olarak kayıtlı uygulamanın version değerini PATCH /webadmin/api/applications/{application} ile artırın; daha sonra köküne index.html içeren bir ZIP yükleyin ve içindeki ilgili varlık URL'lerini kullanın. Başarılı bir yanıt, paket sürümünü, etkinleştirilen değişmez entry_url'yi, dosya sayısını ve genişletilmiş bayt boyutunu ve ayrıca yenilenen uygulama tanımını döndürür. Kurulu sürümlerin üzerine yazılamaz. Doğrulama ve arşiv güvenliği hataları, errors[0].path = application_package (veya çok parçalı alan için application_package.package) kapsamında yapılandırılmış JSON 422 hataları döndürür.

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

İçerik planları, önceden yüklenmiş CMS Medya Kitaplığı kayıtlarını yerel medya destekli bloklara atayabilir. Kullanmakmedia_idveyaasset_idAçıkimage,navbar-brand,sidebar-brand,file,download, Vevideoeşleşen türden medya içeren bloklar. Kullanmakmedia_idveyaasset_idAçıkhero,section,card,cta, Vecontent_headermedya blok arka plan görüntüsü olduğunda, isteğe bağlı olaraksettings.background_positionVesettings.background_overlay. Kullanmakgallery_itemsveyagallery_media_idsAçıkgallerygörüntü medya kayıtlarını içeren bloklar; API, yazarken gönderilen Galeri öğesi sırasını korurblock_media.position. Kart içeriği görüntüleri için aşağıdaki gibi normal iç içe yapıyı oluşturun:card->card_body->imageve koymedia_idçocuk üzerindeimageengellemek. İçerik planları hâlâ reddediliyorremote_urlVesource_url; aracılığıyla dosya yüklePOST /webadmin/api/mediaveya onaylanmış bir genel dosya URL'sini aracılığıyla içe aktarınPOST /webadmin/api/media/fetchönce, sonra döndürülenleri atayınmedia.id.

İçerik planları açık taslak veya staged-update modlarını kullanır. Uygulamadan önce doğrulayın ve yayını ayrı onaya bağlı tutun. Mevcut canlı sayfalar doğrudan değiştirilmek yerine sahipliği doğrulanmış bir staged update gerektirir.

Plan onaylı Medya Kütüphanesi kayıtlarını kullanabilir. Uzak getirme, yükleme ve diğer kaynak işlemleri ayrı endpoint ve izinleri kullanır; plan tanımlamak bu izinleri vermez. Değişiklikten önce mevcut endpointleri keşfedin.

Bearer-token JSON yazmaları token yetkilendirmesini kullanır. Asgari kimlik doğrulamasız keşif yanıtı içerik erişimi vermez. Gerekli kapsam için yukarıdaki Authentication ve Capabilities bölümlerine bakın.

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:

Beklenen durumlar:

• 401 invalid_internal_api_token eksik, geçersiz, iptal edilmiş, süresi dolmuş veya artık kullanıcı tarafından desteklenmeyen belirteçler için
• 403 missing_internal_api_capability eksik yetenekler için
• 403 delegated_site_access_denied kişisel bir belirteç canlı kapsamı dışındaki bir siteyi hedeflediğinde
• 403 delegated_workflow_access_denied sayfa sahibi sayfayı mevcut iş akışı durumunda düzenleyemediğinde
• 403 delegated_operation_denied kurulum düzeyindeki işlemler için kişisel belirteçleri reddeden
• 403 delegated_network_access_denied, çözümlenen IP kişisel belirteç izin verilenler listesinin dışında olduğunda
• 429 personal_api_token_rate_limit_exceeded kişisel tavana ulaşıldığında; istemciler doğrulama hataları için Retry-After
• 422'yi dikkate almalıdır

admin.render'yi ve System'ye erişebilen bir kullanıcı tarafından oluşturulan bir belirteci gerektirir. JSON yanıtı, izin verilenler listesine eklenen System Updates ekranı için oluşturulan yönetici HTML'yi içerir; ?format=html doğrudan text/html'yi döndürür, böylece operatör araçları anlık görüntüyü yerel bir tarayıcıya yükleyebilir ve görsel karşılaştırma için ekran görüntüleri yakalayabilir. Uç nokta salt okunurdur ve güncelleme durumuna tıklamamalı, yüklememeli, yayınlamamalı veya değiştirmemelidir.

engagement.read gerektirir. Desteklenen filtreler status, site_id, page_id, block_id, search ve per_page'dir. Yanıtlar yorum gövdesini, durumu, spam puanını/nedenlerini, kaynak sayfa/blok referanslarını ve zaman damgalarını içerir ancak ziyaretçi karmalarını, IP karmalarını veya kullanıcı aracısı değerlerini açığa çıkarmaz.

engagement.moderate gerektirir. Desteklenen durumlar şunlardır: pending, approved, rejected, spam ve hidden.

engagement.read gerektirir. Desteklenen filtreler status, site_id, page_id, block_id ve per_page'dir. Yanıtlar, derecelendirme satırlarının yanı sıra toplam, ortalama ve değer sayımı özetlerini içerir ancak ziyaretçi karmalarını, IP karmalarını veya kullanıcı aracısı değerlerini göstermez.

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

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

• API'nin anlamadığı plan alanları, 422 ve kararlı kod unsupported_plan_fields ve her birinin hata yolu adlarıyla reddedilir; kabul edilen anahtar kümesi mode planının kapsamına alınmıştır, bu nedenle bir modda anlamlı olan bir anahtar diğerinde hala reddedilir
• site tanıtıcısı veya kimliği çözümlenmelidir
• Yerel ayar mevcut olmalı ve hedef site için etkinleştirilmelidir
• düzen mevcut olmalıdır
• yol çakışması sayfa oluşturmayı engeller
• blok türü yayınlanmalı ve kullanılabilir olmalıdır
• çocuk desteği mümkün olduğunda blok sözleşmelerine uymalıdır
• içerik planı blok ağaçları iç içe children kullanmalıdır; düz id, parent_id, block_id, slot_type_id ve block_type_id ilişki alanları reddedilir çünkü API, veritabanı kimliklerine ve üst öğe atamasına sahiptir
• block translations, seçilen plan yerel ayarı için title, subtitle ve content gibi doğrudan alan anahtarlarını içermelidir; translations.en.title gibi yerel ayar anahtarlı şekiller sessizce göz ardı edilmek yerine reddedilir
• section, container, stack, split, cluster gibi sarmalayıcı bloklar, grid, card, card_body, card_footer, sticky-navbar ve sidebar-navigation, boş genel krom olarak doğrulanamayacak şekilde alt bloklar içermelidir; split tam olarak iki doğrudan alt öğe gerektirir ve her iki taraf da yuvalanmış bir stack
• Kullanıcıya yönelik metin çeviri satırlarına aittir
• Paylaşılan ayarlar paylaşılan olarak kalır
• yeni veya değiştirilen temel ayarlar, keşfedilen blok başına yazma şemasıyla eşleşmelidir; bilinmeyen alanlar ve geçersiz değerler alan yollarıyla reddedilir
• geçmişte bilinmeyen ayarlar okunabilir kalır ve ilgisiz güncellemelerden etkilenmez; tam olarak değişmemiş bir değer PATCH'ye eşlik edebilir ancak bildirilmemiş bir alanın değiştirilmesine izin vermez
• apply yazmadan önce tekrar doğrular
• apply işlemseldir
• İçerik uygulama hala yayınlamayı reddeder, site oluşturma, medya içe aktarma, uzaktan getirme, desteklenmeyen üzerine yazma, desteklenmeyen değiştirme ve silme işlemleri
• Shared Slot oluşturma, daha sonraki bir aşama açık taslak güvenli mutasyon sözleşmeleri eklemediği sürece yalnızca oluşturma olarak kalır
• Gezinme öğesi kaynak uç noktaları açık güncellemeyi, görünürlüğü, yeniden sıralamayı ve içerik dışında silme işlemlerini destekler yetenek korumaları ile

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

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

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

renderability, yapay zeka/operatör araçlarına yönelik bir plan sağlığı özetidir. Başarılı bir yapılandırılmış sayfa planı normalde 0'de wrapper_blocks_without_children, text_blocks_without_visible_content ve button_blocks_without_label_or_url'ye sahip olmalıdır. 0'nin üzerindeki html_blocks, planın Güvenilir HTML kaçış kapısını kullandığı anlamına gelir; araçlar bunu yalnızca açık operatör onayıyla ve yalnızca birinci sınıf blok türleri içeriği temsil edemediğinde yapmalıdır.

İç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.

Navigasyon öğeleri link_type'yi taşır: custom_url (varsayılan, güvenli bir dahili yol veya http(s) URL gerektirir), page (aynı sitedeki bir sayfa için page_id gerektirir; etiket sayfa adına geri döner) veya group (alt öğelerini açan ve URL taşımayan bir etiket). Yalnızca bir group, zaten bağlı olan parent_id ile oluşturulan children'yi kabul eder, bu nedenle açılır liste, POST artı öğe başına PATCH yerine tek bir plandır. İçerik planları bir düzeyde yuvalanır; daha derin ağaçlar POST /navigation-menus/{menu}/items kullanır. Desteklenmeyen bir link_type, custom_url.

'ye zorlanmak yerine isimle reddedilir

page_slot_shared_slots[].page, created kullanılarak aynı planla oluşturulan sayfaya veya mevcut bir sayfa kimliğine atıfta bulunabilir. shared_slot, aynı planda daha önce oluşturulmuş bir Shared Slot'ye veya aynı sitedeki mevcut bir Shared Slot tanıtıcısına atıfta bulunabilir.

İçerik planları, tüm blok yazma işlemleri ve Shared Slot atamalarından sonra tamamlanmış bir sayfa sürümünü ve yeni oluşturulan Shared Slot başına bir tamamlanmış sürümü kaydeder. Mevcut sayfa atama planları, etkilenen sayfa başına bir değişiklik öncesi güvenlik sürümünü kaydeder. Slot değişimi ve aşamalı tanıtım, açık güvenlik kontrol noktalarını korur. Değişmeyen ardışık yakalama, en son tam anlık görüntüyü yeniden kullanır ve ayrı bir yakalama olayını kaydeder; bağımsız HTTP istekleri ayrı işlemler olarak kalır. Sürüm ayrıntısı okumaları, en son yakalama olaylarını içeren sınırlı inspection.capture_history'yi ve bir has_more işaretini içerir. Bkz. Revizyonlar.

• ö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

• 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

Blok kataloğu, depolama sahipliği ve sayfa oluşturma sözleşmeleri için Blok Türü Sözleşmeleri bölümüne bakın. Şemalar CMS Envanteri'ni tamamlar; erişim izni vermez ve yalnızca insan tarafından düzenlenebilen bir bloğu API üzerinden yazılabilir hale getirmez.

CMS 1.105.9'dan itibaren blok türü keşfi ve içerik sözleşmesi kayıtları, mevcut yanıta eklenen bir authoring_settings_schema nesnesi içerir. Önceki settings_schema yanıt biçimleri korunur. Şema revizyonu 1, yayımlanmış tüm temel blokları kapsar ve mode, unknown_fields ve fields alanlarını sunar. Her alan; türünü, izin verilen seçenekleri, aralık ve uzunluk sınırlarını, null/boş değerle temizleme davranışını, güncellemede gönderilmeyen değerin korunmasını ve varsa closed_reason gerekçesiyle birlikte ayrı writes.admin, writes.create, writes.patch kararlarını açıklar.

Yazmadan önce bu işlem kurallarını okuyun. Blok oluşturulurken kabul edilen bir alan, PATCH ile otomatik olarak yazılabilir değildir. İletişim formunun teslimat ve gizlilik alanlarında mevcut PATCH kısıtlamaları korunur. HTML yalnızca insan tarafından düzenlenebilir; medya referansları kendi ilişki alanlarını kullanır. Alan şemaları izin sağlamaz ve harici içerik sağlayıcılarını sorgulamaz.

İçerik planları ve slot bloğu POST işlemleri, bilinmeyen anahtarları ve geçersiz değerleri yazmadan önce reddeder. PATCH yalnızca değişiklikleri doğrular ve mevcut ayarlarla birleştirir. Yazım hatası içeren aligment, görünür etkisi olmayan bir ayar olarak kabul edilmez; geçersiz alignment değeri de mevcut seçimi sessizce temizlemek yerine reddedilir. Gönderilmeyen alanlar güncellemede varsayılan değer eklemez. Bildirilen uyumluluk karşılıkları desteklenir: Slider için fade, slide değerine; Gallery için masonary, masonry değerine dönüştürülür. Oluşturma ayarlarındaki mevcut Contact Form metin anahtarları dil çevirisi yazıcısı tarafından işlenir; PATCH bu metinler için translations kullanır. Tamsayılar sessizce sınır içine çekilmez, uzun metinler sessizce kesilmez. Columns için plain, Split için stack gibi mevcut oluşturma varsayılanları korunur.

Geçmişteki bilinmeyen veya hatalı biçimli değerler okunabilir kalır, mevcut geri dönüşlerle gösterilir ve ilgisiz güncellemelerde korunur. İstemci, aynı geçmiş alanı yalnızca sunucu bu değeri tam olarak ilgili mevcut blokla karşılaştırabiliyorsa gönderebilir. Bu istisna bilinmeyen ayar ekleme veya değiştirme izni vermez. Yeni bloklar ve tam değiştirme istekleri yeni içerik yazımıdır; geçmiş değer istisnasından yararlanamaz. Güvenilir klonlama, hazırlık kopyası oluşturma ve revizyon geri yükleme işlemleri kayıpsız depolama yollarını korur.

Şeması olmayan eklentiler mevcut ayar davranışlarını korur. Eklentiler, blok tanımı veya manifest üzerinden skaler kurallara sahip isteğe bağlı bir şema bildirebilir. Geçersiz bildirim, diğer temel blokları engellemeden yalnızca ilgili şema kapsamındaki yazmaları durdurur. Uygulama ayarları, etkin simgeler ve Dynamic Content bağları, ortak alan denetiminden sonra kendi özel doğrulayıcılarını kullanmaya devam eder.

Sunucu operatörleri mevcut içeriği düzenlemeden önce salt okunur uyumluluk raporu için php artisan webblocks:blocks:audit-settings çalıştırabilir. Komut ayar değerleri yerine blok kimliklerini, alan yollarını ve hata kodlarını bildirir. Onarım yapmaz, sağlayıcı sorgulamaz ve uyumsuz ayar varsa çıkış kodu 1 döndürür. --limit=100, raporlanan blok sayısını sınırlar; üst sınır 1000'dir. Özet yine de tüm taramayı sayar. Denetim harici sağlayıcı veya uygulama sağlığını değil, skaler şema uyumluluğunu kontrol eder. Şemasız eklentiler ayrı sayılır. Yeni veya değiştirilen bildirilen ayarlar 128 alan, 256 KiB, 32 iç içe düzey ve 4096 düğümle sınırlıdır; bu sınırlar değişmeyen geçmiş verilere geriye dönük uygulanmaz.