Headless CMS Nedir: API Tabanlı İçerik Yönetimi

WordPress'te bir tema kurup içerik yazdığınızda, o içerik veritabanına kaydedilir ve aynı sistem bunu doğrudan HTML olarak ekrana basar; içerik yönetimi ile sunum katmanı burada iç içedir. Headless CMS nedir sorusunun cevabı, tam olarak bu bağın koparılmasıdır: içerik bir API üzerinden dışarı verilir, ekranda nasıl görüneceğine ise bambaşka bir sistem karar verir.

Headless CMS ne anlama gelir

"Headless" terimi, CMS'in görsel "kafasının" — yani frontend'in ve tema katmanının — sökülmüş olmasından geliyor. Geleneksel bir CMS'te içerik veritabanı, yönetim paneli ve şablon motoru tek bir uygulama içinde birleşiktir; WordPress, Joomla ve Drupal'ın klasik kurulumları bu modeli temsil eder.

Headless CMS'te ise geriye yalnızca içerik yönetimi ve API katmanı kalıyor. İçeriği bir web sitesinde, mobil uygulamada, akıllı saatte ya da dijital tabelada göstermek isteyen her istemci aynı API'den veri çeker, sunum mantığını kendi ortamında kurar. Contentful, Sanity, Strapi ve Storyblok bu kategorinin bilinen örnekleri arasında yer alıyor.

Geleneksel CMS'ten temel fark

İki mimarinin veriyi nasıl döndürdüğüne bakmak, farkı somutlaştırıyor. Geleneksel bir WordPress kurulumunda tarayıcı bir sayfa istediğinde sunucu PHP çalıştırır ve doğrudan hazır HTML döner. Headless kurulumda ise istemci bir API endpoint'ine istek atar, karşılığında yapılandırılmış veri (genelde JSON) alır:

curl https://api.example.com/content/blog-posts/headless-cms-nedir

{
  "title": "Headless CMS Nedir",
  "slug": "headless-cms-nedir",
  "body": "...",
  "publishedAt": "2026-06-01",
  "author": { "name": "Editör Adı" }
}

Bu JSON'u alan frontend, kendi şablon motoruyla (React, Vue, Svelte ya da başka bir sistem) HTML'e dönüştürür. Aynı JSON verisi aynı anda bir mobil uygulamaya da, akıllı bir ekrana da servis edilebilir; içerik bir kez oluşturulur, her kanalda ayrı biçimde sunulur.

Bu model, içerik stratejisinde de bir bakış değişikliği gerektiriyor. Geleneksel CMS'te editörler genelde "bu sayfa böyle görünecek" diye düşünürken, headless yapıda "bu içerik hangi alanlardan oluşuyor" diye düşünmek gerekiyor. Başlık, özet, gövde metni ve öne çıkan görsel gibi alanlar, sunumdan bağımsız yapısal birimler hâline geliyor.

İçerik tipi tasarımı örneği

Bu bakışı somutlaştırmak için çoğu headless CMS'de bir "blog yazısı" içerik tipinin nasıl tanımlandığına bakmak faydalı olur. Aşağıdaki şema, alanların hangi veri türünü taşıdığını ve hangilerinin zorunlu olduğunu gösteren tipik bir taslaktır:

contentType: blog-post
fields:
  - name: title
    type: string
    required: true
  - name: slug
    type: string
    required: true
    unique: true
  - name: body
    type: richText
    required: true
  - name: featuredImage
    type: asset
    required: false
  - name: author
    type: reference
    references: author
  - name: tags
    type: array
    items: string

Bu şema hem yönetim panelindeki formu hem de API'nin döndüreceği JSON'un yapısını belirliyor. Alan tipleri (richText, asset, reference gibi) CMS'e göre değişse de mantık aynı kalıyor: her alan, sunumdan bağımsız, yeniden kullanılabilir bir veri birimi.

Sürüm kontrolü de headless yapıda daha doğal bir kavram. Çoğu headless CMS, içerik değişikliklerini taslak ve yayında sürümler olarak ayrı tutuyor. Bu ayrım, birden fazla editörün aynı içerik üzerinde çalıştığı büyük ekiplerde çakışmaları önlemeye yardımcı oluyor.

REST ve GraphQL API tercihi

Headless CMS'ler genelde iki API stiliyle çalışıyor. REST API her içerik türü için ayrı endpoint sunuyor, öngörülebilir ve basit bir yapı kuruyor:

GET /api/posts
GET /api/posts/headless-cms-nedir
GET /api/authors/editor-adi

GraphQL ise tek bir endpoint üzerinden, istemcinin tam olarak ihtiyaç duyduğu alanları sorgulamasına izin veriyor:

query {
  post(slug: "headless-cms-nedir") {
    title
    body
    author {
      name
    }
  }
}

REST'te genelde birden fazla istek gerektiren ilişkili veri — yazı, yazar, kategori — GraphQL'de tek istekte toplanabilir. Bu fark, ağ isteği sayısını azaltmak isteyen mobil uygulama ekipleri için belirleyici olabilir; buna karşılık REST, önbellekleme ve hata ayıklama açısından daha basit kalır.

Çok kanallı içerik dağıtımının avantajı

Headless mimarinin en somut kazancı, "bir kez oluştur, her yerde yayınla" (create once, publish everywhere) prensibidir. Bir haber sitesini düşünün: aynı makalenin web sitesinde, mobil uygulamada, Apple News entegrasyonunda ve bir dijital tabelada aynı anda görünmesi gerekebilir.

Geleneksel CMS'te her kanal için ayrı entegrasyon yazmak ya da içeriği kopyalamak gerekir. Headless yapıda ise tek bir API çağrısı aynı veriyi her kanala taşır; içerik ekibi tek bir yerde düzenleme yapar, teknik ekip her kanalın sunumunu bağımsız geliştirir.

Bu ayrım, geliştirici özgürlüğünü de artırır. Frontend ekibi, içerik modelinden bağımsız olarak istediği teknolojiyi — Next.js, Astro, SvelteKit, native mobil — seçebilir. CMS güncellemesi ya da değişimi frontend'i yeniden yazmayı gerektirmez; API sözleşmesi aynı kaldığı sürece iki katman birbirinden habersiz gelişebilir.

JAMstack ve statik site üreticileriyle uyum

Headless CMS, JAMstack mimarisiyle (JavaScript, API, Markup) doğal bir eşleşme kuruyor. Statik site üreticileri — Next.js, Astro, Hugo, Gatsby — derleme sırasında headless CMS'ten içerik çeker ve önceden oluşturulmuş statik HTML dosyaları üretir:

// build sirasinda CMS'ten veri cekme (basitlestirilmis ornek)
export async function getStaticProps() {
  const res = await fetch('https://api.example.com/content/blog-posts');
  const posts = await res.json();
  return { props: { posts } };
}

Bu yaklaşım, sayfaların CDN üzerinden statik dosya olarak sunulmasını sağlar; veritabanı sorgusu her istekte değil, yalnızca içerik değiştiğinde çalışır. Sonuç, geleneksel dinamik CMS'e kıyasla belirgin biçimde daha hızlı sayfa yükleme süreleridir.

Önizleme ve webhook mekanizması

Statik üretim hız kazandırırken bir soru doğuruyor: editör bir taslağı kaydettiğinde, henüz derlenmemiş statik sitede bunu nasıl görecek? Çözüm genelde iki parçadan oluşur. CMS bir "önizleme modu" token'ı üretir. Frontend bu token'ı gördüğünde içeriği derleme zamanında değil, istek anında CMS'ten çeker.

Bu önizleme isteği tipik olarak şöyle çalışır:

curl "https://example.com/api/preview?secret=PREVIEW_TOKEN&slug=headless-cms-nedir"

Bu istek, siteyi geçici olarak taslak verileri gösteren bir moda alır. Editör, değişikliği canlıya almadan önce sonucu görebilir. Yayına alma anında CMS, önceden tanımlanmış bir webhook URL'sine bildirim gönderir; bu webhook hosting sağlayıcısında (Vercel, Netlify gibi) yeni bir build tetikler. Statik dosyalar böylece birkaç saniye ile birkaç dakika içinde güncel içerikle yeniden üretilir. Editör açısından deneyim, geleneksel CMS'teki "kaydet ve yayınla" akışına yakındır; farkı, arka planda bir derleme adımının çalışmasıdır.

Ne zaman headless, ne zaman geleneksel CMS seçilmeli

Her proje headless mimariden fayda görmüyor. Tek bir web sitesi işleten, teknik ekibi küçük olan ya da içerik editörlerinin canlı önizleme beklediği projelerde geleneksel bir CMS genelde daha az sürtünmeli bir seçimdir.

Headless CMS şu durumlarda anlamlı hâle geliyor:

• İçerik birden fazla kanalda (web, mobil, IoT, dijital tabela) yayınlanacaksa.
• Frontend ekibi belirli bir framework'te (React, Vue, native mobil) çalışıyorsa.
• Yüksek trafik altında performans ve ölçeklenebilirlik kritikse.
• İçerik modelinin uzun vadede farklı sunum katmanlarına taşınması bekleniyorsa.

Platformlar da kendi içinde bir yelpazeye yayılıyor. "API-first" olarak anılan Contentful ya da Sanity gibi araçlar baştan API etrafında tasarlanmıştır; yönetim paneli, API'nin bir istemcisi gibi çalışır. Buna karşılık WordPress gibi geleneksel sistemler, REST API ya da WPGraphQL eklentisiyle sonradan "headless'laştırılabilir". Bu ikisi arasında, hem paneli hem API'yi baştan birlikte tasarlayan Strapi gibi açık kaynak seçenekler de yer alıyor.

Headless CMS'in getirdiği ek karmaşıklık

Headless mimarinin bedeli, iki ayrı sistemi birlikte yönetme yüküdür. İçerik editörleri geleneksel CMS'in "ne görüyorsan onu alırsın" (WYSIWYG) önizlemesine alışkınsa, headless kurulumda içeriğin canlı sitede nasıl görüneceğini görmek için ayrı bir önizleme entegrasyonu kurulmalıdır. Bu entegrasyon çoğu headless CMS'de ekstra geliştirme gerektirir.

İçerik modelleme de baştan dikkatli yapılmalıdır. Geleneksel CMS'te sayfa yapısını sonradan değiştirmek nispeten kolayken, headless CMS'te içerik tipleri ve alanlar API sözleşmesinin parçası olduğu için her değişiklik onu tüketen tüm frontend'leri etkiler. Büyük ekiplerde bu durum, içerik stratejisi ve governance sürecinin CMS seçiminden önce netleşmesini gerektirir.

Bu governance süreci pratikte bir belge hâline getirilmelidir. Hangi içerik tiplerinin var olacağı, hangi alanların zorunlu olacağı, kimin yeni alan ekleyebileceği ve API sözleşmesinde değişiklik yapılmadan önce hangi ekiplerin onayının gerektiği baştan yazılmalıdır. Bu belge olmadan, bir editörün "sadece küçük bir alan eklemek" istemesi bile birden fazla frontend'i beklenmedik biçimde bozabilir.

Ekip yapısı da genelde büyüyor. Küçük bir WordPress sitesinde tek bir kişi hem içerik girer hem temayı düzenler. Headless kurulumda ise içerik modelini tasarlayan biri, API'yi tüketen bir frontend geliştiricisi ve genellikle webhook/build süreçlerini yöneten bir DevOps sorumlusu gerekir. Maliyet tarafı da göz ardı edilmemelidir: headless CMS genelde ayrı bir frontend geliştirme ve barındırma maliyeti getirir, geleneksel CMS ise tek bir barındırma faturasıyla çalışır.

Proje küçükse ve tek kanala hizmet ediyorsa, bu ek karmaşıklık çoğu zaman kazandırdığından fazlasını götürür. Küçük ekipler için orta bir yol da vardır: WordPress gibi geleneksel bir CMS, REST API ya da WPGraphQL eklentisiyle kısmen headless modda kullanılabilir. Editörlerin alışık olduğu panel korunurken frontend ayrı bir teknolojiyle geliştirilebilir.

Doğru seçim, projenin kanal sayısına, ekip yapısına ve uzun vadeli büyüme planına bağlıdır. Bir proje headless mimariye geçmeden önce içerik modelini kâğıt üzerinde çıkarıp hangi alanların gerçekten tüm kanallarda ortak olduğunu görmek, sonradan API sözleşmesini kırmaktan çok daha ucuza gelir. JAMstack ekosistemi hakkında daha fazla teknik referans için jamstack.org'un mimari dokümantasyonuna bakmak, hangi statik site üreticisinin hangi headless CMS ile daha iyi entegre olduğunu görmek açısından faydalıdır (jamstack.org).

Yazan Celil Uyanikoglu

Bilgisayar mühendisiyim; 25 yılı aşkın süredir bilgi işlem sektörünün içindeyim. Bu blogu 2020'de, işimde her gün karşılaştığım sorunların çözümlerini bir yere yazmak için açtım: Linux, güvenlik, tarayıcılar, yapay zeka araçları. Yazdığım her rehberi önce kendi bilgisayarımda ya da sunucumda deniyorum; çalıştığını görmediğim adımı yayınlamam. Hatalı ya da eskimiş bir şey görürsen iletişim sayfasından yaz — düzeltirim.