API Referansı

Bu sayfa, Kilavuz’un genel API’sinin nasıl çağrılacağını ve kimlerin hangi uç noktalara erişebildiğini özetler. API tabanı https://api.kilavuz.app üzerinden hizmet verir.

Genel sözleşme

İçerik türü: JSON (istek ve yanıt gövdeleri). Markdown indirme uç noktası text/markdown döner.
Kimlik doğrulama: Oturum çerezi veya Authorization: Bearer <token> başlığı. Her iki yöntem de aynı kullanıcı bağlamıyla sonuçlanır.
Hata kodları: API, standart HTTP durum kodlarını kullanır.
- 400 — istek gövdesi doğrulanamadı.
- 401 — oturum yok veya süresi dolmuş.
- 403 — kullanıcı yetkili değil (örneğin yönetici uç noktasına sıradan kullanıcı isteği).
- 404 — kaynak bulunamadı.
- 500 — sunucu hatası; hata gövdesi İngilizce kalır.

Uç noktalar

Markdown’a dışa aktarma

POST /api/question-review/export-markdown

Belirli bir projeye ait tüm etkin (silinmemiş) soruları hiyerarşik numaralandırma ile birlikte Markdown biçiminde döner.

İstek gövdesi

{
  "projectId": "ckxxxxxxxxxxxxxxxx",
  "include": ["questions"]
}

include alanı isteğe bağlıdır; belirtilmediğinde yalnızca sorular alınır.

Yanıt başlıkları

Content-Type: text/markdown; charset=utf-8
Content-Disposition: attachment; filename="<project-slug>.md"

Yanıt gövdesi

Örnek:

# Proje adı

1. İlk kök soru
  1.1. İlk alt soru
  1.2. İkinci alt soru
    1.2.1. Daha derin alt soru
2. İkinci kök soru

Numaralar kökten başlar; her düzey için iki boşlukluk girinti uygulanır. Bu çıktı, app/src/question-review/export.ts içindeki saf renderQuestionsAsMarkdown işlevi tarafından üretilir.

Sağlık kontrolü

GET /healthz

API konteyneri 3001 portunda dinler; /healthz uç noktası HTTP 200 ve {"status":"ok"} gövdesiyle yanıt verir. Ayrıntılar docs/deploy/kilavuz-readiness.md içindedir.

Sürüm ve uyumluluk

API, semantik sürümlemeye uymaz; uç noktalar eklenirken geriye dönük uyumluluk korunur. Bir uç noktanın kaldırılması veya davranışının değişmesi en az bir sürüm öncesinde bu blogda duyurulur.

Yetkilendirme matrisi

Uç nokta	Sahibi	Yönetici
`POST /api/question-review/export-markdown`	Evet	Evet
`GET /api/admin/users`	Hayır	Evet
`GET /api/admin/billing/subscriptions`	Hayır	Evet

Sıradan bir kullanıcının yönetici uç noktasına yaptığı istek, seçilen dilden bağımsız olarak 403 döner.