Muhammet Şafak — Sunumlar

Tahmin edilebilir bir API'nin 7 katmanı

İstemcinin şaşırmadığı bir API, yedi küçük kararın tutarlılığıdır.

Muhammet Şafak3 Ekim 2026

Akış

Dört durak

Kaynak ve durum koduKatman 1 ve 2
Liste uçlarıKatman 3: sayfalama, filtre, sıralama
Yanıt ve hataKatman 4 ve 5
Sürüm ve sözleşmeKatman 6 ve 7

Yedi katman

Her katman bir tutarlılık kararı

Kaynak: URL isim tabanlı ve çoğul, eylemi HTTP yöntemi taşır.
Durum: Başarı 2xx, istemci hatası 4xx, sunucu hatası 5xx.
Liste: page, per_page, sort, order her uçta aynı adla.
Zarf: Her yanıt aynı iskelette: success, data, message, errors.
Hata: Hata error.code, error.message, error.details olarak döner.
Sürüm: Breaking değişiklik yeni sürüm ister.
OpenAPI: Sözleşme koddan önce yazılır.

Katman 1 · Kaynak ve yöntem

Eylemi URL değil, yöntem taşır

Eylemi URL değil, yöntem taşır
Yöntem	Anlamı	Örnek
GET	Oku	`GET /users/42`
POST	Oluştur	`POST /users`
PUT	Tamamen güncelle	`PUT /users/42`
PATCH	Kısmen güncelle	`PATCH /users/42`
DELETE	Sil	`DELETE /users/42`

Katman 2 · Durum kodu

Durum kodu sonucu söyler

Her hata için 200 OK dönüp gövdeye "error": true yazmak çalışır ama REST prensibine aykırı.
Sınıf	Kodlar	Anlamı
2xx	`200 · 201 · 204`	Başarılı; oluşturuldu; içerik yok
4xx	`400 · 401 · 403 · 404 · 422`	Hatalı veri, kimlik, yetki, kaynak yok, doğrulama
5xx	`500`	Sunucu tarafında beklenmeyen hata

Katman 3 · Sayfalama

Bir sayfanın künyesi

2current_pagelast_page: 15
20per_pageÜst sınır: min($adet, 100)
21–40from – toBu sayfadaki kayıtlar
287totalToplam kayıt

Kaynaktaki örnek · OFFSET

Sayfa büyüdükçe OFFSET pahalanır.

On bininci sayfaya gitmek için veritabanının 200.000 kaydı okuyup geçmesi gerekiyor; çözümlerden biri cursor pagination.

Katman 4 · Yanıt zarfı

Her yanıt aynı iskelette

İstemci her uçta aynı dört alanı okur: success, data, message, errors.

response.json

1{2"success": true,3"data": {},4"message": null,5"errors": null6}

Katman 4 · Yanıt zarfı

Liste de aynı zarfta

Sayfalı liste data.items ve data.meta olarak döner; zarf değişmez.

response.json

1{2"success": true,3"data": {4  "items": [],5  "meta": {6    "current_page": 1,7    "per_page": 15,8    "total": 243,9    "last_page": 1710  }11},12"message": null,13"errors": null14}

Katman 5 · Hata sözleşmesi

Hata da bir sözleşmedir

code makine için sabittir, message insan için değişebilir, details ek bağlam taşır.

error.json

1{2"error": {3  "code": "VALIDATION_FAILED",4  "message": "Gönderilen veriler doğrulanamadı.",5  "details": [6    {7      "field": "email",8      "message": "Geçerli bir e-posta adresi giriniz."9    },10    {11      "field": "phone",12      "message": "Telefon numarası zorunludur."13    }14  ]15}16}

Katman 4 ve 5

Zarf ve hata kuralları

200 ile hataHata için 200 + "error": true çalışır ama REST'e aykırı; cache ve loglama bozulur.
BiçimHata kodu büyük harf ve alt çizgiyle: QUOTA_EXCEEDED.
KodlarYeni kod eklenebilir, eski kod kaldırılmamalı.
ÖlçekTek istemcili küçük serviste durum kodu ve kısa mesaj yeter.

Katman 6 · Sürümleme

Üç strateji, tercih URI

Tercih URI sürümlemesi: okunabilirlik, ayrı dokümantasyon, ayrı rota grupları.
Strateji	Örnek	Takas
URI	`GET /api/v1/users`	Log ve proxy'de net görünür; URL'leri çoğaltır
Header	`X-API-Version: 2`	URL temiz kalır; eksik header belirsizlik doğurur
Query	`GET /api/users?version=2`	Başlangıçta pratik; proxy ve CDN görmeyebilir

Katman 6 · Sürümleme

Temel düzeyde: hangi değişiklik yeni sürüm ister?

Uyumlu

Yanıta yeni bir alan eklemek.
İsteğe bağlı bir parametre eklemek.
Hata mesajlarını zenginleştirmek.

Breaking

Var olan bir alanı kaldırmak veya yeniden adlandırmak.
Zorunlu bir parametre eklemek.
Yanıt yapısını ya da durum kodunu değiştirmek.

Kullanımdan kaldırma

En az 6–12 ay önceden duyurun.

Dış istemcilere açık bir API'de en az 6-12 aylık bir deprecation süreci makul.

Katman 6 · RFC 8594 (2019) · RFC 9745 (2025)

Sürümün ömrünü başlıkla bildirin

RFC 8594: Mayıs 2019, Informational. RFC 9745: Mart 2025.
Başlık	Belge	Ne söyler
`Deprecation: @1780272000`	RFC 9745	Ne zaman kullanımdan kaldırıldığını; değer bir tarih, true geçersiz
`Sunset: Sat, 31 Oct 2026 23:59:59 GMT`	RFC 8594	Ne zaman yanıt vermeyeceğini
`Link: <…/docs/migrate-v2>; rel="deprecation"`	RFC 9745	Geçiş belgesinin adresini

Katman 7 · Contract-first

Önce sözleşme, sonra kod

Adım 1: SözleşmeOpenAPI 3.0.3
Adım 2: Paralel işbackend · UI · test
Adım 3: MockPrism
Adım 4: Doğrulamacontract testing
Adım 5: Güncellemesözleşme ya da kod

Katman 7 · OpenAPI

Sözleşme koddan önce yazılır

Örnek sözleşmenin şema kesiti. /orders ucu status filtresini pending, completed, cancelled ile sınırlar.

openapi.yaml

1components:2schemas:3  Order:4    type: object5    required: [id, status, total]6    properties:7      id:8        type: integer9      status:10        type: string11      total:12        type: number

Katman 7

Contract-first ne zaman değer?

Küçük projeTek geliştirici, küçük proje: contract-first overkill olabilir.
Çok tüketiciWeb, mobil, üçüncü taraf: kesinlikle zaman kazandırıyor.
Uzun ömürYıllarca yaşayacak API'de sözleşme bir karar kaydıdır.

Teşekkürler

muhammetsafak.com.tr

Yedi katman, yedi tutarlılık sözü. Ayrıntılar altı kaynak yazıda.