Bir Şeyler Yapıyoruz

Başlarken

Üç şey yeter: adres, anahtar ve JSON gövde.


Adres	`https://www.birseyleryapiyoruz.com/api/articles`
Biçim	JSON — istekte `Content-Type: application/json`, en çok 256 KB
Kimlik	`Authorization: Bearer bsy_…` (okuma ya da yazma yetkili anahtar)
Yeni yazı	Her zaman taslak girer, sitede görünmez. `PATCH {"taslak": false}` ile yayına çıkar.
Site	Her yazma isteği site önbelleğini hemen tazeler; değişiklik anında görünür.

İlk istek: son üç yazı

curl "https://www.birseyleryapiyoruz.com/api/articles?limit=3" \
  -H "Authorization: Bearer $API_KEY"

Kimlik doğrulama

Anahtarı platform üretir. Anahtar yalnız üretildiği anda bir kez gösterilir; veritabanında kendisi değil, özeti tutulur.

Her istekte

Authorization: Bearer bsy_TCteCi…

Yetki	İzin verdiği
`read`	Liste, tek yazı ve /validate.
`write`	Okumanın hepsi + ekleme, değiştirme, düzenleme, yayına alma, silme.

Anahtar yönetimi (proje klasöründe)

"gelistiriciler-module__GHkoHq__tCom"># Yeni anahtar — yalnız bu sefer gösterilir
npm run api-anahtar -- olustur uretici-1 write "Otomatik yazı üretici"

"gelistiriciler-module__GHkoHq__tCom"># Anahtarlar: ad, yetki, son kullanım
npm run api-anahtar -- liste

"gelistiriciler-module__GHkoHq__tCom"># Anında kapat (bu anahtarla gelen istekler 403 alır)
npm run api-anahtar -- iptal uretici-1

Anahtar yoksa 401 UNAUTHORIZED, geçersiz ya da iptal edilmişse 403 FORBIDDEN. Anahtar adreste (?key=) kabul edilmez; adresler kayıtlara düşer.

Yanıt biçimi

Bütün yanıtlar aynı zarfta gelir. Önce ok alanına bakman yeter.

Başarı

{
  "ok": true,
  "data": { … },
  "meta": { … },
  "corrections": [ … ]
}

Hata

{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "fields": [ … ]
  }
}

Alan	Anlamı
`data`	Yazı nesnesi; listede yazı dizisi.
`meta`	Yalnız listede: page, limit, total, pages.
`corrections`	API'nin senin yerine düzelttikleri (ör. kategori yazımı). Varsa gelir.
`error.code`	Makinenin okuyacağı kod — §09.
`error.fields`	Her neden ayrı: field, code, message; gerekiyorsa expected, received, allowed.

Yanıtlar önbelleğe alınmaz (Cache-Control: no-store). Yazı dönen her yanıtta X-Version başlığı vardır — §08.

Yazı nesnesi

Gönderdiğin gövde. Yıldızlı alanlar zorunlu; bilmediğimiz her alan ek alan olarak saklanır.

Alan	Tür	Kural
`slug *`	string	Adres: /yazilar/<slug>. Yalnız a-z 0-9 - (Türkçe harf yok), en çok 60 karakter, benzersiz, değiştirilemez.
`baslik *`	string	25–60 karakter. Sondaki nokta kendiliğinden kalkar.
`ozet *`	string	120–200 karakter, tek paragraf. Kartta 3 satır görünür.
`tarih *`	string	YYYY-AA-GG, gerçek bir gün. Liste yeniden eskiye bu alana göre sıralanır.
`kategori *`	string	Beş kategoriden biri — §05. Büyük/küçük harf fark etmez.
`giris *`	string	Bölümlerden önceki giriş, 1–2 paragraf Markdown.
`bolumler *`	dizi	3–6 öğe, her biri yalnız { baslik, icerik }.
`ikon`	string	Yazının kendi kategorisinden bir ikon — §05. Boşsa kategorinin varsayılanı.
`yazar`	string	En çok 60 karakter.
ek alanlar	herhangi	Ad harfle başlar (harf, rakam, _), en çok 20 alan, toplam 8 KB, en çok 3 kat iç içe. Yanıtta ekAlanlar içinde döner.

API'nin eklediği alanlar

Alan	Anlamı
`taslak`	true: sitede görünmez. Yalnız PATCH ile değişir.
`url`	Yazının sitedeki adresi.
`kelime · okumaDk`	Kelime sayısı ve okuma süresi (dakikada 200 kelime).
`surum`	Her değişiklikte 1 artar — §08.
`olusturuldu · guncellendi`	ISO tarih.

Gönderilemez: taslak (yalnız PATCH), _id, olusturuldu, guncellendi, kaynak, surum ve eski alanlar arama, bolum, alan, icerik, tur → RESERVED_FIELD.

Senin yerine düzelttiklerimiz

Gereksiz hata çıkmasın diye gövde denetimden önce temizlenir ve yapılan her düzeltme corrections ile bildirilir: kenar boşlukları ve görünmez karakterler silinir, satır sonları birleşir, art arda boş satırlar teke iner; slug ve ikon küçük harfe, kategori doğru yazımına çevrilir ("değişim" → "Değişim", eski ad "Değişmek" → "Değişim"); bölüm başlığının başındaki numara (1. ) kalkar.

Kategoriler ve ikonlar

Tek kategori seçilir: yazının ana sorusu hangisine aitse. İkon yalnız anahtar olarak yazılır ve kendi kategorisinden seçilir; ilk ikon varsayılandır.

[CSR]Cesaret

bayrakvarsayılan
merdiven
roket
kivilcim
kapi
ampul
mikrofon

[DYN]Dayanıklılık

nabizvarsayılan
kalkan
capa
pil
fidan
dag

[FRK]Farkındalık

gozvarsayılan
geri-al
buyutec
soru
terazi
kalem

[DGS]Değişim

pusulavarsayılan
dongu
yol-ayrimi
cip
parilti

[VZN]Vizyon

durbunvarsayılan
hedef
kup
grafik
harita

İçerik kuralları

Toplam 600–1200 kelime (3–6 dk okuma). Bölüm başlığı 2–6 kelime; numara eklenmez, site numaralar.

Kullanılır

Biçim	Yazımı
Paragraf	boş satırla ayrılır
Vurgu	`kalın` · `italik`
Alıntı	`> Tek cümle.` — en çok 2
Liste	`- madde` · `1. adım`
Ara başlık	`### Başlık`
Bağlantı	`[metin](https://…)`

Kullanılmaz

# / ## başlık — bölüm başlığı ayrı alanda
#### ve daha derin başlık
HTML etiketleri
Görsel ![…](…)
Tablo ve kod bloğu
http(s):// ile başlamayan bağlantı

Hata, ilgili alan ve satır numarasıyla döner.

Dil ve ton: Türkçe, sade ve samimi; okura "sen" diye seslenir. Kısa cümleler, somut örnek, net bir ana fikir. Reklam dili ve doldurma cümle yok. Konular: girişimcilik, teknoloji, yapay zekâ, yatırım ve sektörden notlar.

Uç noktalar

Yedi uç nokta; renkler Branding Kit'in beş alan rengi.

Yöntem	Adres	Ne yapar
GET	`/api/articles`	Liste (sayfalı, filtreli)
POST	`/api/articles`	Yeni yazı (taslak)
POST	`/api/articles/validate`	Yalnız denetle, kaydetme
GET	`/api/articles/{slug}`	Tek yazı
PUT	`/api/articles/{slug}`	Tümüyle değiştir
PATCH	`/api/articles/{slug}`	Kısmi düzenle · yayına al · taslağa çek
DELETE	`/api/articles/{slug}`	Sil (arşive taşı)

GET/api/articlesokuma yetkisi

Yazıları listele

En yeniden eskiye sıralı. Varsayılan olarak yalnız künye gelir; içerik için include=content.

Parametre	Değerler	Varsayılan
`status`	all · draft · published	all
`category`	Ad ya da adres biçimi: Değişim, degisim (eski adlar da)	—
`q`	Başlıkta arama	—
`page`	1 ve üzeri	1
`limit`	1–100	20
`include`	content	—

İstek

curl "https://www.birseyleryapiyoruz.com/api/articles?status=draft&category=degisim&limit=10" \
  -H "Authorization: Bearer $API_KEY"

200 OK

{
  "ok": true,
  "data": [ { "slug": "…", "baslik": "…", "taslak": true, "kategori": "Değişim", "kelime": 617, … } ],
  "meta": { "page": 1, "limit": 10, "total": 1, "pages": 1 }
}

Olası hatalar: 400 INVALID_QUERY · 401 · 403

POST/api/articlesyazma yetkisi

Yazı ekle

Yazı taslak olarak girer. Aynı slug’da yazı varsa üzerine yazılmaz.

Gövde (metinler kısaltıldı; gerçek yazı 600–1200 kelime)

{
  "slug": "yapay-zekayla-ilk-urunu-cikarmak",
  "baslik": "Yapay zekâyla ilk ürünü çıkarmak",
  "ozet": "Model seçmek işin en kolay kısmı. Asıl soru hangi sorunu, kimin için, ne kadar iyi çözdüğün…",
  "tarih": "2026-10-15",
  "kategori": "Değişim",
  "ikon": "parilti",
  "yazar": "Bir Şeyler Yapıyoruz",
  "giris": "Yapay zekâ araçları ürün çıkarmayı hiç olmadığı kadar ucuzlattı. Ama ucuzlayan şey **denemek**…",
  "bolumler": [
    { "baslik": "Önce sorun, sonra model", "icerik": "En sık yapılan hata…\n\n> Model değişir; çözdüğün sorun kalır." },
    { "baslik": "İlk sürüm tek iş yapsın", "icerik": "İlk sürümün tek bir işi iyi yapması yeter…\n\n- Birinci soru\n- İkinci soru" },
    { "baslik": "Ölç, sonra büyüt", "icerik": "Kaç kişinin ikinci kez geldiğine bak…" }
  ],
  "kaynakUrl": "https://example.com/kaynak",
  "etiketler": ["yapay zekâ", "ürün"]
}

İstek

curl -X POST "https://www.birseyleryapiyoruz.com/api/articles" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @yazi.json

201 Created · X-Version: 1

{
  "ok": true,
  "data": {
    "slug": "yapay-zekayla-ilk-urunu-cikarmak",
    "url": "https://www.birseyleryapiyoruz.com/yazilar/yapay-zekayla-ilk-urunu-cikarmak",
    "taslak": true,
    "baslik": "Yapay zekâyla ilk ürünü çıkarmak",
    "ozet": "Model seçmek işin en kolay kısmı…",
    "tarih": "2026-10-15",
    "kategori": "Değişim",
    "ikon": "parilti",
    "yazar": "Bir Şeyler Yapıyoruz",
    "giris": "Yapay zekâ araçları…",
    "bolumler": [{ "baslik": "Önce sorun, sonra model", "icerik": "…" }],
    "kelime": 617,
    "okumaDk": 4,
    "surum": 1,
    "olusturuldu": "2026-10-15T09:00:00.000Z",
    "guncellendi": "2026-10-15T09:00:00.000Z",
    "ekAlanlar": { "kaynakUrl": "https://example.com/kaynak", "etiketler": ["yapay zekâ", "ürün"] }
  },
  "corrections": ["kategori \"değişim\" → \"Değişim\""]
}

Olası hatalar: 409 SLUG_TAKEN · 422 VALIDATION_FAILED · 400 · 413 · 415 · 401 · 403

POST/api/articles/validateokuma yetkisi

Kaydetmeden denetle

Gövde POST ile aynıdır. Hiçbir şey kaydedilmez; üretici yazılım göndermeden önce kendini sınar.

200 OK

{
  "ok": true,
  "data": {
    "gecerli": true,
    "kelime": 617,
    "okumaDk": 4,
    "yazi": { "slug": "…", "baslik": "…", "kategori": "Değişim", "…": "temizlenmiş hali", "ekAlanlar": { } }
  },
  "corrections": [ "…" ]
}

Geçmezse: 422 VALIDATION_FAILED — POST ile aynı hata listesi.

GET/api/articles/{slug}okuma yetkisi

Tek yazıyı oku

Taslak da olsa döner; içerik dahil. X-Version başlığı güncel sürümü verir.

İstek

curl "https://www.birseyleryapiyoruz.com/api/articles/yapay-zekayla-ilk-urunu-cikarmak" -H "Authorization: Bearer $API_KEY"

Olası hatalar: 404 NOT_FOUND · 401 · 403

PUT/api/articles/{slug}yazma yetkisi

Tümüyle değiştir

Yazının tamamı yeniden gönderilir; gönderilmeyen isteğe bağlı ve ek alanlar silinir. Gövdede slug yazılmayabilir (adresteki kullanılır). Yayındaki yazı yeniden taslağa döner; yayın kararı yeniden verilir. Oluşturulma tarihi korunur, sürüm artar.

İstek

curl -X PUT "https://www.birseyleryapiyoruz.com/api/articles/yapay-zekayla-ilk-urunu-cikarmak" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Expected-Version: 3" \
  -d @yazi.json

Olası hatalar: 404 · 412 VERSION_CONFLICT · 422 SLUG_IMMUTABLE · 422 VALIDATION_FAILED

PATCH/api/articles/{slug}yazma yetkisi

Kısmi düzenle, yayına al, taslağa çek

Yalnız gönderdiğin alanlar değişir. İçerik değişirse yazının son hali baştan denetlenir.

Gövde	Sonuç
`{ "yazar": "Ad Soyad" }`	Yalnız yazar değişir.
`{ "ikon": null, "kaynakUrl": null }`	İsteğe bağlı alan ve ek alan silinir (ikon varsayılana döner).
`{ "taslak": false }`	Yayına alır; içerik yeniden denetlenmez.
`{ "taslak": true }`	Taslağa çeker; yazı siteden hemen kalkar.
`{ "kategori": "Vizyon", "ikon": "grafik" }`	Kategori ve ikon birlikte değişir.

Yayına al

curl -X PATCH "https://www.birseyleryapiyoruz.com/api/articles/yapay-zekayla-ilk-urunu-cikarmak" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taslak": false}'

Olası hatalar: 404 · 412 · 422 SLUG_IMMUTABLE · 422 MISSING_FIELD (zorunlu alana null) · 422 VALIDATION_FAILED

DELETE/api/articles/{slug}yazma yetkisi

Sil

Yazı siteden hemen kalkar. Bir kopyası arşivde saklanır; API ile geri getirilmez, gerekirse arşivden elle geri alınır.

İstek

curl -X DELETE "https://www.birseyleryapiyoruz.com/api/articles/yapay-zekayla-ilk-urunu-cikarmak" -H "Authorization: Bearer $API_KEY"

200 OK

{ "ok": true, "data": { "slug": "yapay-zekayla-ilk-urunu-cikarmak", "silindi": true } }

Olası hatalar: 404 · 412

Sürüm kontrolü

İki yazılımın birbirinin değişikliğini ezmemesi için. İsteğe bağlı ama önerilir.

Yazıyı okurken yanıttaki X-Version başlığını (ya da gövdedeki surum) sakla.
PUT, PATCH ya da DELETE’te X-Expected-Version olarak geri gönder.
Yazı bu arada değiştiyse işlem yapılmaz: 412 VERSION_CONFLICT. Güncel hali okuyup yeniden dene.

PATCH /api/articles/yapay-zekayla-ilk-urunu-cikarmak
X-Expected-Version: 3

Standart If-Match başlığını gönderme: barındırma altyapısı onu kendisi yorumlayıp başarılı yanıtı bozuyor.

Hata kodları

Doğrulama hataları tek seferde, alan alan gelir; ilk hatada durulmaz.

422 Unprocessable Entity

{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Yazı 3 nedenle kaydedilmedi.",
    "fields": [
      { "field": "ozet", "code": "SUMMARY_LENGTH", "message": "Özet 120–200 karakter olmalı (şu an 96).", "expected": "120–200", "received": 96 },
      { "field": "ikon", "code": "ICON_INVALID", "message": "\"roket\" Değişim ikonu değil.", "received": "roket", "allowed": ["pusula", "dongu", "yol-ayrimi", "cip", "parilti"] },
      { "field": "bolumler[1].icerik", "code": "MARKDOWN_FORBIDDEN", "message": "# ve ## başlık kullanılamaz… (satır 3)" }
    ]
  }
}

HTTP durumları

HTTP	error.code	Ne zaman
400	`INVALID_JSON`	Gövde geçerli bir JSON değil.
400	`INVALID_QUERY`	Liste parametresi hatalı; ayrıntı fields içinde.
401	`UNAUTHORIZED`	Authorization: Bearer … başlığı yok.
403	`FORBIDDEN`	Anahtar geçersiz, iptal edilmiş ya da yalnız okuma yetkili.
404	`NOT_FOUND`	Bu slug'da yazı yok.
409	`SLUG_TAKEN`	POST: aynı slug'da yazı zaten var.
412	`VERSION_CONFLICT`	X-Expected-Version, yazının güncel sürümüyle eşleşmiyor.
413	`PAYLOAD_TOO_LARGE`	Gövde 256 KB'tan büyük.
415	`UNSUPPORTED_MEDIA_TYPE`	Content-Type: application/json değil.
422	`VALIDATION_FAILED`	Yazı kurallara uymuyor; her neden fields içinde.
422	`SLUG_IMMUTABLE`	Slug değiştirilmeye çalışıldı.
500	`INTERNAL_ERROR`	Bizim hatamız; yanıttaki requestId ile bildir.

Alan hataları · fields[].code

Kod	Ne zaman
`MISSING_FIELD`	Zorunlu alan yok ya da boş.
`INVALID_TYPE`	Alan beklenen türde değil (expected).
`UNKNOWN_FIELD`	Bölümde baslik ve icerik dışında alan var.
`SLUG_INVALID`	Slug yalnız a-z, 0-9 ve tire içerebilir; en çok 60 karakter; ayrılmış adres olamaz.
`TITLE_LENGTH`	Başlık 25–60 karakter değil.
`SUMMARY_LENGTH`	Özet 120–200 karakter değil.
`AUTHOR_LENGTH`	Yazar 60 karakterden uzun.
`DATE_INVALID`	Tarih YYYY-AA-GG değil ya da gerçek bir gün değil (2026-02-30).
`CATEGORY_INVALID`	Beş kategoriden biri değil (allowed).
`ICON_INVALID`	İkon yazının kategorisine ait değil (allowed).
`SECTION_COUNT`	Bölüm sayısı 3–6 değil.
`SECTION_TITLE_LENGTH`	Bölüm başlığı 2–6 kelime / en çok 60 karakter değil.
`CONTENT_EMPTY`	Bölüm metni boş.
`WORD_COUNT`	Yazı 600–1200 kelime değil (Markdown işaretleri sayılmaz).
`MARKDOWN_FORBIDDEN`	Yasak biçim: # / ## / #### başlık, HTML, görsel, tablo, kod bloğu ya da http(s) olmayan bağlantı. Satır numarasıyla.
`QUOTE_LIMIT`	2'den fazla alıntı (>).
`RESERVED_FIELD`	Gönderilemeyen alan: taslak, _id, olusturuldu, guncellendi, kaynak, surum, arama, bolum, alan, icerik, tur.
`EXTRA_FIELD_INVALID`	Ek alanın adı, sayısı, boyutu ya da iç içeliği kurala uymuyor.
`SLUG_IMMUTABLE`	PATCH / PUT ile slug değiştirilemez.

field boşsa hata yazının bütünüyle ilgilidir (kelime sayısı, alıntı sayısı). Konum bolumler[1].icerik biçimindedir.

Örnek akış

Üretici yazılımın bir yazıyı yayına kadar götürmesi.

POST /validate — kurallardan geçiyor mu? Geçmiyorsa fields’a göre yeniden üret.
POST /api/articles — taslak olarak ekle.
GET /api/articles?status=draft — editör taslakları görür, okur.
PATCH { "taslak": false } — onaylanan yazı yayına çıkar, sitede hemen görünür.
PUT Yeniden üretilen sürüm — yazı yeniden taslağa döner.
DELETE Gerekmeyen yazı kalkar; kopyası arşivde durur.

Uçtan uca test (bütün uç noktalar, 127 kontrol)

API_KEY=bsy_… npm run api:test