Public Content API v1

Content API v1, Münderecat web, mobil ve dış istemcileri için ortak anonim salt-okunur içerik sınırıdır.

Base URL: https://api.munderecat.com/v1
OpenAPI:  https://docs.munderecat.com/openapi/content-api-v1.json

API anahtarı, cookie veya Supabase bilgisi gerekmez. Yüzey yalnız GET ve CORS preflight için OPTIONS kabul eder; istemciler credentialsız istek göndermelidir.

İlk okuma

Yeni oturum önce catalog ile current content context’i alır:

curl --fail-with-body --compressed \
  -H 'Accept: application/json' \
  https://api.munderecat.com/v1/catalog

Catalog cevabındaki releaseContext.contentContextId sonraki resource çağrılarını pinler. data.chapters[].chapterId ile chapter okunur:

GET /v1/contexts/{contextId}/targets
GET /v1/contexts/{contextId}/chapters/{chapterId}
GET /v1/contexts/{contextId}/chapters/{chapterId}/headings
GET /v1/contexts/{contextId}/chapters/{chapterId}/targets/{targetKey}?binding={bindingId}
GET /v1/contexts/{contextId}/addresses
GET /v1/contexts/{contextId}/routes/{locale}/{bookAlias}/{chapterAlias}

Target isteğindeki bindingId, aynı context’in target registry cevabından alınmalıdır. Bugünkü registry tr-latn, tr-ottoman ve en-rnk-en targetlarını taşır. Her target her bölümde bulunmayabilir; eksik İngilizce 200 cevabında resultState: "unavailable" olarak döner.

Sürümleme ve hatalar

/v1/catalog yeni oturum için current context’i gösterebilir. Catalogdan sonra istemci aynı context altında devam etmelidir; catalog değiştiğinde eski ve yeni release’ler sessizce birleştirilmez.

Başarılı route çözümü stable bookId, chapterId, canonicalAddress ve canonical veya redirect durumunu taşır. Bilinmeyen, gone veya kullanılamayan locale için okunabilir bir bölüm uydurulmaz. available, pending, unavailable ve invalid durumları istemcinin içerik kararlarıdır; network/configuration hatası ayrı transport hatası olarak ele alınmalıdır.

Production istemcileri repository’deki generated TypeScript clientı ve @munderecat/reader-core adapterını kullanmalıdır. Raw response doğrudan render edilmemeli; context, target binding, stable anchor ve reconstruction doğrulamaları geçmeden içerik gösterilmemelidir.

İsteğe bağlı pasaj haritası

Sözleşme kabul edilmiş pasaj verisi için üç ayrı okuma işlemi içerir:

GET /v1/contexts/{contextId}/chapters/{chapterId}/passages/{passageReleaseId}
GET /v1/contexts/{contextId}/passage-releases/{passageReleaseId}/identities/{identityId}
GET /v1/contexts/{contextId}/passage-releases/{passageReleaseId}/map

Yerel runtime chapter/aile işlemlerini kurulu tr-passage-1 verisine, genel haritayı bir kez hazırlanmış yerel yayın dizinine bağlar. Production runtime aynı sonuçları ayrı R2 pasaj yayınından okur; Supabase sorgusu veya chapter başına fan-out yapmaz. Capability etkin değilse sonuç unavailable olur; istemci bunu “pasaj kaydı yok” diye yorumlamamalıdır.

@munderecat/reader-core içindeki SOURCE_PASSAGE_RELEASE sabiti kabul edilmiş release kimliği ve kökünü taşır. getChapterPassages(chapterId, { signal }) ve getPassageIdentity(identityId, { signal }), getPassageMap({ signal }) bu pini kullanır. Yeni capability ana content context, target registry veya mevcut core/çeviri verisini değiştirmez.

Chapter çıktısı placements, edges ve compilationMaps koleksiyonlarını ayrı tutar. Identity çıktısı ailenin bütün yerleşimlerini yerel exactText, kitap, bölüm ve stable cümle sınırlarıyla döndürür. Birincil veya tercih edilen yerleşim bu listeden çıkarılmaz. Paneldeki metin eşitliği, ayrı bir exact repetition profile kararı veya atıf aktarımı değildir.

Map çıktısı tam metin içermez: 142 aile, 309 yerleşim, kitap/chapter kimlikleri, cümle sınırları, kısa önizleme, 84 yönlü ilişki ve 24 derleme haritasını taşır. Derleme haritasının scopeChapterId alanı kapsadığı bölümü belirtir; sıralı üyeler ve 816 bölgenin rolleri korunur. Aile seçildiğinde tam metin identity işlemiyle ayrıca alınır. Bu kapsam bütün kısa cümle/paragraf tekrarları değildir.

15 Eylül 2026 yayını CONTENT_PASSAGES_PUBLICATION_ID ile sabitlenmiştir. Diğer yayınların kimlikleri ve önceki operation revision kimlikleri değişmemiştir.

Pasaj okuyucu çalışma notu kapsamı ve doğrulama komutlarını açıklar.