git:20260704.12791fe to git:20260707.abd2d2b

35 added, 35 removed. Audit A to A.

---

name: api-design

description: |

- API sözleşmesi tasarımı: tutarlı kaynak/adlandırma, hata modeli, sürümleme, sayfalama,

- geriye-uyum ve OpenAPI. Tüketiciyi kırmadan evrilen, tahmin edilebilir arayüz üretir.

- Trigger phrases: "api tasarımı", "api design", "api sözleşmesi", "api versiyonlama", "openapi", "swagger", "rest sözleşmesi", "kırıcı api değişikliği"

+ API contract design: consistent resources/naming, error model, versioning, pagination,

+ backward compatibility, and OpenAPI. Produces a predictable interface that evolves without breaking consumers.

+ Trigger phrases: "api design", "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change"

---

- # API Tasarımı

+ # API Design

- Amaç: tüketicinin **tahmin edebileceği**, kırılmadan **evrilebilen** bir sözleşme. Bir kez yayınlanan

- public API bir taahhüttür; kırıcı değişiklik pahalıdır. Yığın-bağımsız (REST temel; GraphQL/gRPC benzer ilkeler).

+ Goal: a contract the consumer can **predict** and that can **evolve** without breaking. Once published, a

+ public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles).

- ## Kontrol listesi

- - [ ] Kaynak adları **tutarlı** (çoğul isim, `kebab`/`camel` tek stil), fiil değil kaynak

- - [ ] HTTP semantiği doğru: GET (yan etkisiz) · POST · PUT/PATCH · DELETE; doğru **durum kodu**

- - [ ] **Hata modeli** tek tip: makine-okunur kod + insan mesajı + (varsa) alan detayları

- - [ ] **Sürümleme** stratejisi belli (URL `/v1` veya header); kırıcı değişiklik yeni sürüm

- - [ ] **Sayfalama/filtre/sıralama** büyük koleksiyonlarda tanımlı ve tutarlı

- - [ ] **Geriye-uyum**: alan ekleme additive; alan silme/anlam değiştirme kırıcı → sürüm

- - [ ] **İdempotency** (POST/ödeme gibi) gerekiyorsa anahtar destekli

- - [ ] Sözleşme **OpenAPI**'de belgeli; örnek istek/yanıt var (`docs-writer` ile koordine)

+ ## Checklist

+ - [ ] Resource names are **consistent** (plural nouns, a single `kebab`/`camel` style), resources not verbs

+ - [ ] Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct **status code**

+ - [ ] A uniform **error model**: machine-readable code + human message + (if any) field details

+ - [ ] A clear **versioning** strategy (URL `/v1` or header); a breaking change means a new version

+ - [ ] **Pagination/filtering/sorting** defined and consistent on large collections

+ - [ ] **Backward compatibility**: adding a field is additive; removing a field or changing its meaning is breaking → version

+ - [ ] **Idempotency** (for POST/payment-like cases) supported via a key when needed

+ - [ ] The contract is documented in **OpenAPI**; example request/response present (coordinate with `docs-writer`)

- ## Nasıl

- 1. **Kaynağı modelle** — fiil değil isim: `POST /orders` (✓), `POST /createOrder` (✗).

- 2. **Durum kodları**: 200/201/204 · 400 doğrulama · 401/403 yetki · 404 · 409 çakışma · 422 · 429 · 5xx. Anlamlı kullan.

- 3. **Hata sözleşmesi** — her hata aynı şekil:

+ ## How

+ 1. **Model the resource** — a noun not a verb: `POST /orders` (✓), `POST /createOrder` (✗).

+ 2. **Status codes**: 200/201/204 · 400 validation · 401/403 authorization · 404 · 409 conflict · 422 · 429 · 5xx. Use them meaningfully.

+ 3. **Error contract** — every error has the same shape:

```json

- { "code": "ORDER_NOT_FOUND", "message": "Sipariş bulunamadı", "details": [] }

+ { "code": "ORDER_NOT_FOUND", "message": "Order not found", "details": [] }

```

- Stack trace / iç detay sızdırma (`security-scan` ile örtüşür).

- 4. **Sürümleme**: additive değişiklik aynı sürümde; kırıcı (alan sil/yeniden adlandır/zorunlu alan ekle) → `/v2`.

- 5. **Koleksiyon**: sayfalama (cursor veya offset), filtre/sıralama parametreleri; tutarlı zarf.

- 6. **Sözleşmeyi yaz** — OpenAPI/şema; örneklerle. Değişikliği `docs-writer`'a, kırıcıysa `release`/CHANGELOG'a bağla.

+ No stack trace / internal detail leakage (overlaps with `security-scan`).

+ 4. **Versioning**: additive changes in the same version; breaking (remove/rename a field / add a required field) → `/v2`.

+ 5. **Collection**: pagination (cursor or offset), filter/sort parameters; a consistent envelope.

+ 6. **Write the contract** — OpenAPI/schema; with examples. Wire the change to `docs-writer`, and if breaking to `release`/CHANGELOG.

- ## Kırıcı vs additive

- | Additive (güvenli) | Kırıcı (sürüm ister) |

+ ## Breaking vs additive

+ | Additive (safe) | Breaking (needs a version) |

|---|---|

- | Opsiyonel alan/endpoint ekle | Alan sil / yeniden adlandır |

- | Yeni opsiyonel parametre | Zorunlu parametre ekle |

- | Yeni enum değeri (tüketici toleranslıysa) | Tip/anlam değiştir, durum kodu değiştir |

+ | Add an optional field/endpoint | Remove / rename a field |

+ | A new optional parameter | Add a required parameter |

+ | A new enum value (if the consumer is tolerant) | Change a type/meaning, change a status code |

- ## Değişmez kurallar

- 1. **Public API bir taahhüt** — kırıcı değişiklik sessizce yapılmaz; sürüm + duyuru.

- 2. **Tutarlılık > yerel zeka** — tek adlandırma/hata/sayfalama kalıbı tüm API'de.

- 3. **Hata modeli tek tip ve makine-okunur.**

- 4. **İç detay sızdırma** — stack trace / DB hatası tüketiciye gitmez.

- 5. **Sözleşme belgeli** — OpenAPI + örnek; koddan sonra değil, tasarımda.

+ ## Invariant rules

+ 1. **A public API is a commitment** — a breaking change is not made silently; version + announcement.

+ 2. **Consistency > local cleverness** — a single naming/error/pagination pattern across the whole API.

+ 3. **The error model is uniform and machine-readable.**

+ 4. **No internal detail leakage** — a stack trace / DB error does not go to the consumer.

+ 5. **The contract is documented** — OpenAPI + example; at design time, not after the code.