api-contract-review

API Contract Review

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Ne Zaman Kullanılır

• Yeni endpoint / yeni schema
• Public API release öncesi
• Breaking change şüphesi (removed field, type change, required eklenmiş)
• SDK üretimi öncesi
• WS event protokolü değişti

Workflow

1) Spec/handler tespit

• OpenAPI: openapi.yaml, openapi.json, *.openapi.*
• GraphQL: *.graphql, *.graphqls, schema.json
• Route handler: routes/, controllers/, @app.get, @router.post, r.HandleFunc, app.get(...)
• Önceki versiyon yoksa baseline yok → breaking change yerine "ilk sürüm" olarak işaretle.

2) İsimlendirme & şekil

• Path: kebab-case, plural noun (/orders değil /order_list).
• JSON case tutarlı (snake_case veya camelCase — repo geneline tek seç).
• Resource hiyerarşisi anlamlı (/orders/{id}/items).
• Verb yerine resource (/getUser ❌ → GET /users/{id} ✅).

3) HTTP method semantiği

• GET safe + idempotent + cache'lenebilir.
• POST non-idempotent (create); kritik endpoint'lerde Idempotency-Key header zorunlu.
• PUT idempotent full replace.
• PATCH idempotent partial — RFC 7396 (merge) veya RFC 6902 (json-patch) seç.
• DELETE idempotent.

4) Status code

• 200 body var, 204 body yok.
• 201 Created + Location header POST'ta.
• 202 Accepted async iş için + status URL.
• 400 validation, 401 unauthenticated, 403 unauthorized, 404 not found, 409 conflict, 422 semantic validation, 429 rate limit, 5xx server.
• Error body RFC 7807 problem+json: {type, title, status, detail, instance}.

5) Versiyonlama

• URL path (/v1/...) veya Accept: application/vnd.example.v1+json.
• Breaking change → yeni major (/v2/...); eski major en az 6 ay veya next-major release'e kadar yaşamalı (Sunset header).
• Non-breaking (yeni endpoint, yeni opsiyonel field) → minör; aynı majör altında.

6) Idempotency

• POST/PATCH ödeme, sipariş, kullanıcı oluşturma → Idempotency-Key zorunlu, server hash'i 24-72 saat saklasın.
• Retry-Safe pattern: client UUID üretir, server cache'ten aynı response döner.

7) Pagination

• Cursor (opaque string) > offset büyük setlerde (offset = O(n) DB'de).
• Header: Link: <...>; rel="next" veya body: { data, next_cursor, has_more }.
• Limit cap (max 100/sayfa) zorunlu.

8) Auth & scope

• OAuth2 / OIDC scope explicit per endpoint (OpenAPI security:).
• Permission denial → 403 + RFC 7807 type: ".../insufficient-scope".
• Cookie-auth + CSRF token; bearer-only API'lerde CSRF gereksiz.

9) Rate limit

• RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (RFC draft).
• 429 + Retry-After header.

10) Error model homojenliği

• Tüm endpoint aynı error envelope kullanmalı.
• { "error": "..." } ve { "detail": "..." } karışık → tek standart.

11) Breaking change diff

• Önceki spec ile oasdiff veya graphql-inspector diff koştur.
• Breaking: removed field, required eklenmiş, type değişti, enum azaldı, status code değişti.
• Non-breaking: yeni opsiyonel field, yeni endpoint, enum genişledi.

12) GraphQL özel

• Resolver N+1 (DataLoader var mı?).
• Nullability tutarlı (her field nullable yap pattern'i kötü).
• Deprecation: @deprecated(reason: "...") + sunset tarihi.
• Persisted query / APQ üretim için.

13) WebSocket event protokolü

• Event envelope: { type, version, payload, ts, correlation_id }.
• Versioning: payload schema versiyonu envelope'ta.
• Heartbeat protokolü dokumented (ping/pong interval, idle timeout).
• agents/websocket-protocol-auditor ile birlikte review.

Checklist

• Path kebab-case + plural
• JSON case repo geneline uyumlu
• HTTP method semantik doğru
• Status code + RFC 7807 error envelope homojen
• Versiyon stratejisi explicit (URL veya header)
• Idempotency-Key kritik POST'larda
• Cursor pagination + max limit
• OAuth2 scope OpenAPI'de
• Rate limit header
• Breaking change diff (varsa) + sunset planı
• GraphQL: DataLoader + deprecation reason
• WS: envelope + versiyon + heartbeat

Antipattern

• Verb-in-path (/createOrder, /getUser) — REST resource modeline aykırı.
• 200 OK { error: "..." } — status hep 200, error body'de — client retry mantığı bozulur.
• Required field eklemek minör versiyonda — silent breaking.
• string field üstüne ek constraint (max length) eklemek breaking sayılabilir, dökumented olmalı.
• Cursor pagination yokken ?offset=...&limit=... 1M satırlık tabloda — DB tarafı ölür.
• Idempotency-Key yokken POST /payments — duplicate charge riski.
• GraphQL'de Query.users(limit: Int) limit opsiyonel + cap yok → DoS vektörü.
• Versioning header sürümleri merge edilmemiş (Accept: application/json her sürümde aynı) → versioning fiilen yok.

Örnek Agent Davranışı

User: /api-contract-review openapi.yaml
Agent (api-contract-guardian):
1. spec parse + önceki sürümle oasdiff.
2. Tespit: POST /payments Idempotency-Key yok (Critical — duplicate charge).
3. Tespit: GET /v1/users snake_case, GET /v1/orders camelCase (High — client confusion).
4. Tespit: 201 yerine 200 POST /orders (Medium).
5. Tespit: Error body 3 farklı şekilde (High — RFC 7807 standardize et).
6. Delege: security-reviewer auth scope kontrolüne; test-engineer contract test eksiğine.
7. Output: rapor + diff + breaking change tablosu + sunset planı.

Çıktı Formatı

# API Contract Review: <spec/route>

## Critical
- [ ] ... — kanıt: line/diff
## High
## Medium
## Low

## Breaking Changes (vs prev)
- field/type değişiklik tablosu

## Diff (özet)
```yaml
# fixed openapi snippet

Test Eksiği

• contract test (schemathesis/dredd/openapi-test) önerisi