WY · BÖLÜM 07 · FÖY 130

YAZ-130 · Yazılım & Teknik · ~2-3 dk (tek endpoint)

API endpoint kodundan ornekli dokumantasyon (istek/yanit/hata)

Endpoint'in icin istek/yanit/hata orneklerini iceren, README'ye veya API dokumanina dogrudan yapistirilabilecek duzenli bir taslak elde edersin.

Kanca

Endpoint calisiyor, ama dokumana kimse dokunmamis. Sonra baska bir ekip "bu istegi nasil atacagiz, hata donunce ne anlama geliyor" diye gelince is yine sana kaliyor.

Hamle — Claude / ChatGPT (ikisi de calisir)

Prompt — kopyala & yapıştır

Sen bir API dokumantasyon yardimcisisin. Sana bir endpoint'in kaynak kodunu (route + handler) verecegim. Gorevin, SADECE kodda gorunen bilgiden ornekli bir endpoint dokumantasyonu uretmek.

Kurallar:
- Tahmin yurutme. Bir alanin tipi, zorunlu olup olmadigi, dogrulama kurali veya kimlik dogrulama yontemi koddan net cikmiyorsa, o satira "EKSIK: ..." yaz ve neyin belirsiz oldugunu tek cumleyle soyle. Bosluğu kendin doldurma.
- Alan adlarini, yollari ve status kodlarini kodda yazdigi gibi birebir kullan. Kodda olmayan alan, parametre veya hata uydurma.
- Ornek degerleri koddaki tip ve isimden turet (or. "e-posta" alani icin ornek bir e-posta bicimi). Gercek veri, gercek token, gercek anahtar YAZMA; tum ornekleri acikca sahte tut (or. "ornek_deger", "test@ornek.com").
- Kod akisini yorumlayip "muhtemelen sunu yapar" deme; sadece koddan dogrudan okunani yaz.

Ciktiyi tam olarak su basliklarla ver:
1. Ozet: endpoint tek cumleyle ne yapar
2. Metot ve yol: (or. POST /v1/orders)
3. Kimlik dogrulama: koddan cikan yontem; cikmiyorsa EKSIK
4. Istek: header'lar, path/query parametreleri ve govde alanlari — her biri icin ad, tip, zorunlu mu, kisa aciklama. Sonuna kopyalanabilir bir ornek istek ekle (curl veya JSON govde)
5. Basarili yanit: status kodu + ornek JSON govde
6. Hata yanitlari: kodda gecen her hata durumu icin status kodu, ne zaman doner, ornek govde
7. Notlar: rate limit, sayfalama, yan etkiler — yalnizca kodda acikca varsa

Endpoint kodu:
[BURAYA ENDPOINT KODUNU YAPISTIR]

Çıktı

Endpoint'in icin istek/yanit/hata orneklerini iceren, README'ye veya API dokumanina dogrudan yapistirilabilecek duzenli bir taslak elde edersin. Koddan cikmayan her nokta "EKSIK" diye isaretli gelir; boylece neyi elle tamamlaman gerektigini bir bakista gorursun. Tek endpoint icin birkac dakika.

Kariyer çentiği

Dokumantasyon ekipte en cok ertelenen is; sen onu dakikalar icinde ve orneklerle cikarinca "entegrasyonu ona sor" denen, guvenilen kisi olursun.

Sınır

AI yalnizca yapistirdigin kodu gorur; kodun disindaki is kurallarini, gercek dogrulama davranisini ve yan etkileri bilemez, o yuzden yayina almadan once ciktiyi gozden gecir. Gercek token, anahtar veya musteri verisi yapistirma; ornekleri sahte tut.

Örnek — bu prompt ne üretir?

Örnek girdi

// routes/siparis.js
router.post('/v1/siparisler', authMiddleware, async (req, res) => {
  const { urunKodu, adet, teslimatAdresi } = req.body;

  if (!urunKodu || typeof urunKodu !== 'string') {
    return res.status(400).json({ hata: 'urunKodu zorunlu ve metin olmali' });
  }
  if (!Number.isInteger(adet) || adet < 1) {
    return res.status(400).json({ hata: 'adet 1 veya daha buyuk tam sayi olmali' });
  }

  const stok = await stokKontrol(urunKodu);
  if (stok < adet) {
    return res.status(409).json({ hata: 'Yetersiz stok', mevcut: stok });
  }

  const siparis = await Siparis.create({
    kullaniciId: req.user.id,
    urunKodu,
    adet,
    teslimatAdresi,
    durum: 'olusturuldu',
  });

  return res.status(201).json({
    siparisId: siparis.id,
    durum: siparis.durum,
    olusturmaTarihi: siparis.createdAt,
  });
});

Çıktı

POST /v1/siparisler

1. Ozet

Bir kullanici adina, istenen urunun stogu yeterliyse yeni bir siparis kaydi olusturur.

2. Metot ve yol

POST /v1/siparisler

3. Kimlik dogrulama

EKSIK: Route authMiddleware ara katmanini kullaniyor ve req.user.id okuyor, ama bu katmanin kodu verilmedi; hangi yontemin (token / oturum vb.) beklendigi koddan cikmiyor.

4. Istek

Header'lar:

Ad	Zorunlu	Aciklama
Content-Type	Evet	Govde JSON olarak okundugu icin (`req.body`) `application/json` beklenir
Authorization	EKSIK	`authMiddleware`in hangi header'i okudugu koddan gorunmuyor

Path / query parametresi: Yok (kodda gecmiyor).

Govde alanlari:

Ad	Tip	Zorunlu	Aciklama
urunKodu	string	Evet	Bos olamaz ve metin olmali; degilse 400 doner
adet	integer	Evet	1 veya daha buyuk tam sayi olmali; degilse 400 doner
teslimatAdresi	EKSIK	EKSIK	Dogrulanmadan `Siparis.create`e gecirilir; tipi ve zorunlu olup olmadigi koddan cikmiyor

Ornek istek (curl):

```bash

curl -X POST https://[EKSIK: temel URL koddan cikmiyor]/v1/siparisler \

-H "Content-Type: application/json" \

-H "Authorization: [EKSIK: yontem belirsiz]" \

-d '{

"urunKodu": "ornek_urun_kodu",

"adet": 2,

"teslimatAdresi": "ornek teslimat adresi"

```

5. Basarili yanit

201 Created

```json

{

"siparisId": "ornek_siparis_id",

"durum": "olusturuldu",

"olusturmaTarihi": "2026-01-01T00:00:00.000Z"

}

```

EKSIK: siparisId tipi (sayi mi, UUID mi) ve olusturmaTarihi bicimi koddan net cikmiyor; ornek degerler sahtedir.

6. Hata yanitlari

Status	Ne zaman doner	Ornek govde
400	`urunKodu` yok veya string degil	`{"hata":"urunKodu zorunlu ve metin olmali"}`
400	`adet` tam sayi degil veya 1'den kucuk	`{"hata":"adet 1 veya daha buyuk tam sayi olmali"}`
409	Stok istenen adetten az	`{"hata":"Yetersiz stok","mevcut":0}`
EKSIK	`authMiddleware`in dondurdugu hata durumlari (or. 401)	Koddan gorunmuyor

7. Notlar

Yan etki: Basarili istekte veritabaninda bir siparis kaydi olusturulur (Siparis.create).
stokKontrol yalnizca stogu okur; kodda stok dusurme islemi gorunmuyor.
Rate limit ve sayfalama: Kodda yok.

ÜRETİM: TEM 2026 · CLAUDE Bu kayıt eşlenmiş örnek girdi ve çıktı içerir. Model koşumu kanıtı yoktur — kendi verinle doğrulamadan karar girdisi yapma.

Kendi verinle çalıştır

Verini aşağıya yapıştır; prompt seninkiyle birleşip çalıştırmaya hazır tek bloğa dönüşsün. Sonra tek dokunuşla Claude ya da ChatGPT'de aç.

Senin verin

Hazır prompt — verini bekliyor

Sen bir API dokumantasyon yardimcisisin. Sana bir endpoint'in kaynak kodunu (route + handler) verecegim. Gorevin, SADECE kodda gorunen bilgiden ornekli bir endpoint dokumantasyonu uretmek.

Kurallar:
- Tahmin yurutme. Bir alanin tipi, zorunlu olup olmadigi, dogrulama kurali veya kimlik dogrulama yontemi koddan net cikmiyorsa, o satira "EKSIK: ..." yaz ve neyin belirsiz oldugunu tek cumleyle soyle. Bosluğu kendin doldurma.
- Alan adlarini, yollari ve status kodlarini kodda yazdigi gibi birebir kullan. Kodda olmayan alan, parametre veya hata uydurma.
- Ornek degerleri koddaki tip ve isimden turet (or. "e-posta" alani icin ornek bir e-posta bicimi). Gercek veri, gercek token, gercek anahtar YAZMA; tum ornekleri acikca sahte tut (or. "ornek_deger", "test@ornek.com").
- Kod akisini yorumlayip "muhtemelen sunu yapar" deme; sadece koddan dogrudan okunani yaz.

Ciktiyi tam olarak su basliklarla ver:
1. Ozet: endpoint tek cumleyle ne yapar
2. Metot ve yol: (or. POST /v1/orders)
3. Kimlik dogrulama: koddan cikan yontem; cikmiyorsa EKSIK
4. Istek: header'lar, path/query parametreleri ve govde alanlari — her biri icin ad, tip, zorunlu mu, kisa aciklama. Sonuna kopyalanabilir bir ornek istek ekle (curl veya JSON govde)
5. Basarili yanit: status kodu + ornek JSON govde
6. Hata yanitlari: kodda gecen her hata durumu icin status kodu, ne zaman doner, ornek govde
7. Notlar: rate limit, sayfalama, yan etkiler — yalnizca kodda acikca varsa

Endpoint kodu:
[BURAYA ENDPOINT KODUNU YAPISTIR]

Yapıştırdığın veri tarayıcından çıkmaz — WhiteYaka'ya gönderilmez. Prompt panoya kopyalanır; açılan sohbete Ctrl/⌘ + V ile yapıştırırsın.

i Bu föy örnek girdi ve çıktı içerir; yapısal doğrulama ve ölçütlü prompt koşumu henüz kaydedilmedi.

← Tüm bölümler Sıradaki föy: Yeni Fonksiyona Kenar Durum Birim Test İskeleti →

Bülten kaydı kapalı.

Bu sayfa e-posta adresi toplamaz ve liste kaydı başlatmaz. 160 hamlenin tamamı giriş yapmadan açık.