RESTful API Tasarimi 2026: Best Practice ve Anti-Pattern

RESTful API best practice 2026 itibarıyla artık “Roy Fielding doktorasını okudum” tartışmasından çıkıp; sürüm yönetimi, idempotency, rate-limit, hata kontratı ve OpenAPI sözleşmesi gibi operasyonel beklentilerin standardize edildiği bir mühendislik disiplinine dönüştü. Postman’in 2024 State of the API raporuna göre kuruluşların yaklaşık %74’ü “API-first” yaklaşımı benimsediğini beyan ediyor; Stack Overflow 2024 Developer Survey’de profesyonel geliştiricilerin %57.5’i hâlâ REST’i birincil entegrasyon stili olarak kullanıyor. Bu yazıda, gerçek üretim sistemlerinde uygulanan kontrat tasarımı, kaynak modelleme, hata yönetimi ve sürümleme kalıplarını; sık karşılaşılan anti-pattern’lerle birlikte 2400+ kelimelik somut bir referans olarak ele alacağız. Hedef kitle: orta-büyük ölçekli platformlarda backend, platform engineering veya çözüm mimarisi yapan ekipler.

REST, RESTful ve HTTP API: 2026’da Doğru Tanım

Pratikte üç kavram sıklıkla karıştırılıyor. REST, Fielding’in 2000 tezindeki mimari kısıtlardır (uniform interface, stateless, cacheable, layered, code-on-demand opsiyonel, client-server). RESTful, bu kısıtlara “yeterince” uyan bir tasarımı; HTTP API ise sadece HTTP üzerinden çalışan, REST iddiası olmayan endpoint kümesini ifade eder. Richardson Maturity Model’in 3. seviyesi (HATEOAS) endüstride neredeyse yok denecek kadar nadir benimseniyor; Microsoft Azure REST API Guidelines ve Google AIP rehberleri de Level 2 (HTTP fiilleri + kaynak URI + status code) üzerinde duruyor. Yani 2026’da pragmatik hedef, HATEOAS değil; tutarlı kontrat + makine okunabilir şema + operasyonel olgunluk.

Bu pragmatik konsolidasyon, mikroservislerin yaygınlaşmasıyla daha da hızlandı. Servis sınırlarını netleştirmek için Domain-Driven Design ile bounded context çıkardıktan sonra, her bounded context’in dışa açık yüzünü REST sözleşmesi olarak ifade etmek artık endüstri standardı. Bu sözleşmenin iç implementasyondan bağımsız kalması için katmanların ayrıştırılmasında benimsenen tasarım disiplini de aynı derecede belirleyici. Aşağıdaki tablo, dört yaygın API stilini operasyonel kriterlerle karşılaştırıyor.

Kriter	REST	GraphQL	gRPC	WebHook/Event
Sözleşme formatı	OpenAPI 3.1	SDL schema	Protobuf .proto	AsyncAPI 3.0
Tipik latency (p50)	20-80 ms	30-120 ms	5-25 ms	asenkron
Tarayıcı desteği	Tam	Tam	Sınırlı (gRPC-Web)	Sunucu push gerekir
Caching (HTTP)	Yerel destekli	Manuel	Yok	Konu dışı
Public API uygunluğu	Yüksek	Orta	Düşük	Orta
Tooling olgunluğu	Çok yüksek	Yüksek	Yüksek	Orta

REST’in hâlâ baskın olmasının nedeni teknik üstünlük değil, ekosistem: tarayıcılar, CDN’ler, proxy’ler, API gateway’ler, monitoring araçları HTTP semantiklerini varsayar. Yeni bir entegrasyon kanalı açarken bu uyumun değerini hafife alan ekipler, sonradan WAF kurallarından TLS terminasyonuna kadar her katmanda manuel iş yapmak zorunda kalıyor. Daha geniş entegrasyon stratejisi için API entegrasyon: REST, GraphQL ve webhook rehberini inceleyebilirsin.

Kaynak Modelleme ve URI Tasarımı

URI tasarımı görünüşte basit ama mali sonuçları olan bir karar. Microsoft Azure REST API Guidelines ve Google API Improvement Proposals (AIP) ortak bir dil sunuyor: kaynaklar isim (çoğul), fiiller HTTP metodu, hiyerarşi en fazla 2-3 seviye. Aşağıdaki tablo doğru ve yanlış örnekleri yan yana koyuyor.

Amaç	Anti-pattern	Doğru REST	Neden
Sipariş listele	GET /getOrders	GET /orders	Fiil URI’da olmaz
Tek sipariş	GET /order?id=42	GET /orders/42	ID path parametresi
Sipariş iptali	POST /cancelOrder/42	POST /orders/42/cancellations	Sub-resource modeli
Alt kaynak	GET /orderLines?orderId=42	GET /orders/42/lines	Hiyerarşi netleşir
Filtre	GET /orders/status/paid	GET /orders?status=paid	Filtre = query string
Toplu işlem	POST /deleteAll	POST /orders:batchDelete	AIP custom verb kalıbı

İki-üç seviyeden derin hiyerarşi (örn. /customers/12/orders/42/lines/3/taxes/2) bakım maliyetini patlatır; üst seviye kimliklerin alt seviyeden tekrar türetilmesi gerekir mi sorusu her endpoint’te ortaya çıkar. AIP-122 bu yüzden “alt kaynağı düz seviyede de erişilebilir kıl” der: GET /orderLines/{id} mümkün olsun, hiyerarşik sürüm sadece listeleme için kullanılsın.

• İsimlendirme: İngilizce, snake_case yerine kebab-case path; payload’da snake_case veya camelCase tek bir konvansiyon — karıştırma.
• Çoğul mu tekil mi: Koleksiyon her zaman çoğul (/orders), tekil kaynak sadece singleton ise tekil (/users/me/settings).
• İlişkisel ID: İlişkiler için URI bağı (/orders/42/lines); body içindeki ID’leri minimumda tut.
• Versiyon path’i: /v1/orders (URI versioning) en yaygın; header versioning daha temiz ama operasyonel tarafta debug daha zor.

Servis sınırı çıkarımı yaparken yalnız kaynak değil, kimin yazma yetkisi olduğu da önemli. Aynı sipariş kaynağına 3 servis yazıyorsa orada bir modüler monolit aşaması atlanmış demektir; REST endpoint çoğalmadan önce sınırları düzeltmek 6-12 ay sonra refactor maliyetinin onda biri kadar. Kaynak sahipliği ile servis sınırı çakışmadığında ortaya çıkan kontrat erozyonu, geç fark edildiğinde tüm istemci SDK’larını etkileyen breaking change zinciri yaratır.

HTTP Metodları, Status Code ve Idempotency

Üretimde en sık görülen hata sınıfı, HTTP metod semantiklerinin gevşek uygulanması. RFC 9110 (HTTP Semantics) GET, HEAD, PUT, DELETE’i idempotent, GET ve HEAD’i ayrıca safe olarak tanımlar. POST idempotent değildir; PATCH de değildir (resmî olarak). Bu, retry mantığını doğrudan etkiler: ağ kesintisinde otomatik yeniden deneme POST/PATCH için Idempotency-Key başlığı olmadan tehlikeli.

Metod	Safe	Idempotent	Tipik kullanım	Beklenen 2xx
GET	Evet	Evet	Kaynak okuma	200, 304
HEAD	Evet	Evet	Metadata kontrol	200, 304
POST	Hayır	Hayır*	Kaynak oluşturma, RPC-vari aksiyon	201, 202, 200
PUT	Hayır	Evet	Tam yer değiştirme	200, 204
PATCH	Hayır	Hayır	Kısmi güncelleme	200, 204
DELETE	Hayır	Evet	Silme	200, 202, 204

*Stripe, Square ve PayPal’ın yıllardır kullandığı Idempotency-Key kalıbı POST’u operasyonel olarak idempotent yapar. Stripe Idempotent Requests dokümantasyonu, anahtarın 24 saat saklandığını ve aynı anahtarla gelen sonraki isteklerin önceki yanıtı döndüğünü açıklar. Ödeme, sipariş oluşturma, e-posta gönderme gibi yan etkili tüm POST’larda bu kalıp 2026 sonrası beklenen standart hâline geldi.

1. PUT vs PATCH: Tam payload gönderiyorsan PUT; sadece değişen alanları gönderiyorsan PATCH (JSON Merge Patch RFC 7396 veya JSON Patch RFC 6902).
2. Avantaj — PUT: “Last writer wins” semantiği net, conditional If-Match ile optimistic locking kolay.
3. Dezavantaj — PUT: Büyük kaynaklarda her güncelleme tüm payload’u taşır, mobil maliyeti yüksek.
4. Ne zaman seç — PATCH: Mobil-first uygulama, dokümana benzer karmaşık kaynak, kısmi yetki senaryoları.

Status Code Kullanımı: 4xx vs 5xx Ayrımı

Yanlış status code, gözlemlenebilirlik (observability) açısından sessiz bir maliyet. SRE ekipleri 5xx oranını uyarıya bağlar; istemci hatasını 500 döndüren bir endpoint, gece 03:00’te boş yere on-call uyandırır. 4xx ve 5xx ayrımının doğru yapılması, bir API’nin operasyonel olgunluğunun en hızlı sinyalidir.

Durum	Status	Anlam	Retry?
Başarılı oluşturma	201 Created	Location header eklenir	—
Asenkron kabul	202 Accepted	İş kuyrukta	—
Geçersiz JSON	400 Bad Request	İstemci formatı yanlış	Hayır
Auth yok	401 Unauthorized	Token eksik/geçersiz	Token yenile
Yetki yok	403 Forbidden	Kullanıcı izinli değil	Hayır
Yok	404 Not Found	Kaynak bulunamadı	Hayır
Conflict	409 Conflict	State çakışması / ETag uyumsuz	Refresh + retry
Doğrulama	422 Unprocessable	Semantik validasyon hatası	Hayır
Rate-limit	429 Too Many Requests	Retry-After zorunlu	Backoff retry
Sunucu hatası	500 Internal	Beklenmeyen exception	Backoff retry
Bağımlılık	502/503/504	Upstream / overload / timeout	Backoff retry

Hata gövdesi için RFC 9457 Problem Details for HTTP APIs (eski RFC 7807) artık fiili standart. application/problem+json içeriği, type (URI), title, status, detail, instance ve isteğe bağlı domain-spesifik alanlar içerir. Bu format, istemcide hata sınıflandırma kodunu jenerikleştirir, dokümantasyon yükünü düşürür.

Versiyonlama: URI, Header, Content Negotiation

API versiyonlamada üç ana kalıp var; hiçbiri “doğru” değil, hepsinin operasyonel maliyeti farklı. Microsoft Azure rehberi URI versiyonlamayı (/v1/) öneriyor; Google AIP ise major sürüm path’te (/v1/), minor sürüm header’da. GitHub API X-GitHub-Api-Version başlığıyla tarih bazlı versiyon kullanıyor.

Strateji	Örnek	Avantaj	Dezavantaj
URI versioning	/v1/orders	Cache ayrımı net, debug kolay	Aynı kaynak için çoklu URI
Header versioning	Accept-Version: 2	Tek URI, temiz	CDN cache key custom yapılandırma
Content negotiation	Accept: application/vnd.api+json;v=2	HTTP doğal	İstemci karmaşık
Date-based	X-Api-Version: 2026-03-01	Stripe/GitHub kalıbı, breaking change yavaş	Tarih-versiyon eşlemesi gerekli
Query versioning	?v=2	Hızlı geçici çözüm	Anti-pattern: cache, log kirli

Major sürüm yükseltmesi mümkünse parallel run: yeni sürüm yayınla, eski sürümü minimum 6-12 ay yaşat, deprecation header’ı (Deprecation, Sunset — RFC 8594) ekle, müşteri telemetrisini takip et. Stripe’ın 2011’den bu yana yaklaşık 20 versiyonu eş zamanlı yaşatması bu yaklaşımın en iyi bilinen örneği. Public API’lar için pahalı ama müşteri güvenini koruyan tek yöntem.

Servis içi (internal) API’larda mikroservis mimarisi geçişi sırasında parallel run pahalı olur; bunun yerine consumer-driven contract testing (Pact) ile breaking change’leri build zamanında yakalamak daha verimli. Mikroservis ekosisteminde sürüm yönetimi tek başına yeterli değil; servis keşfi, mTLS ve trafik yönetimi gibi katmanların versiyonlama stratejisine eşlik etmesi, geriye dönük uyumluluğu operasyonel bir özellik hâline getirir.

Sayfalama, Filtreleme ve Sıralama

Liste endpoint’leri toplam yükün %50-70’ini taşır; tasarım hatası burada doğrudan veritabanı maliyetine yansır. Offset/limit sayfalama kolay görünür ama büyük tablolarda OFFSET 100000 tarama maliyeti taşır. Modern API’lar cursor-based pagination tercih eder.

• Offset pagination: ?page=10&size=20 — basit, ama büyük offset O(N) maliyet. Ne zaman seç: küçük veri kümeleri, admin paneli.
• Cursor pagination: ?cursor=eyJpZCI6NDJ9&limit=20 — index seek O(log N), sıralı veriler için ideal. Avantaj: stabil sonuç, sonsuz scroll. Dezavantaj: “5. sayfaya atla” mümkün değil.
• Keyset pagination: ?after_id=42&limit=20 — cursor’ın açık hâli, gizlilik gerekmiyorsa daha okunabilir.
• Time-based: ?since=2026-01-01T00:00:00Z — feed/event kaynakları için.

Sayfalama yanıtı zarflama biçimi de standardize edilmeli. Hem GitHub’ın Link header kalıbı (RFC 8288), hem de {"data": [...], "meta": {"next_cursor": "..."}} JSON zarfı yaygın. Tek seçim yapıp tüm endpoint’lerde sabitle. Filtreleme için “JSON:API” spesifikasyonunun ?filter[status]=paid formatı ile basit ?status=paid arasında karar verirken: karmaşık filtre kombinasyonu beklemiyorsan basit query parametre, sorgu DSL’ine ihtiyaç varsa filter+operatör kalıbı (örn. ?filter=amount:gte:100) tercih et.

Senaryo	Önerilen	p99 latency hedef	Tipik sayfa boyutu
Mobil sonsuz scroll	Cursor	< 300 ms	20-30
Admin panel listesi	Offset + total count	< 800 ms	50-100
Reporting / export	Keyset + async job	job tabanlı	500-1000
Event feed	Time-based / cursor	< 200 ms	50-100
Search	Cursor + scoring	< 500 ms	10-25

Güvenlik, Rate-Limit ve Auth Kalıpları

2024 yılında OWASP API Security Top 10 (2023) listesinde Broken Object Level Authorization (BOLA) hâlâ 1. sırada. Yani bir kullanıcının GET /orders/42 ile başka kullanıcının siparişini okuyabilmesi en sık zafiyet. Çözüm endpoint düzeyinde değil, her veritabanı sorgusunun bağlamsal user_id ile filtrelenmesi. Repository katmanı tasarımıyla bu kontrolü tek noktada zorlamak için Repository Pattern faydalıdır.

Auth tarafında 2026’da yaygın seçim OAuth 2.1 + PKCE + JWT access token (kısa ömürlü) + refresh token rotation. mTLS API gateway’de servis-to-servis ekseninde standardize ediliyor. Rate-limit ise kullanıcı bazında değil, çoklu boyutta: kullanıcı, IP, API key, endpoint paterni — Cloudflare, AWS API Gateway, Kong gibi platformlarda token bucket veya sliding window algoritmaları kullanılıyor.

Tier	RPS limit	Burst	Aylık çağrı	Tipik müşteri
Free	5	10	100K	Geliştirici sandbox
Starter	25	50	1M	Küçük startup
Growth	100	200	10M	SaaS scale-up
Business	500	1000	100M	Kurumsal
Enterprise	Özel	Özel	Sınırsız	SLA müzakere

Rate-limit yanıtı için IETF RateLimit Headers draft kalıbı: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset başlıkları ile her yanıtta istemciyi bilgilendir. 429 dönerken Retry-After zorunlu. Bu, agresif retry loop’larının yan etkisiyle self-DoS oluşturmasını engelleyen birinci satır savunma. Header’ların yanı sıra, istemci SDK’larında jittered exponential backoff zorunlu kılınmalı; aksi takdirde rate-limit’in koruyucu işlevi paradoxal bir yoğunluk yaratır.

Sözleşme Önce Yaklaşımı: OpenAPI 3.1 ve Tooling

Postman 2024 raporundaki “API-first” benimseme oranı %74; bu pratikte OpenAPI sözleşmesi kod yazılmadan önce yazılır demek. OpenAPI 3.1 (Şubat 2021’de yayınlandı, JSON Schema 2020-12 uyumu getirdi) artık endüstri varsayılanı. Sözleşme şu zinciri besler: mock server (Prism), kod üretimi (openapi-generator, oapi-codegen), istemci SDK (Stripe, Twilio kalıbı), API gateway konfigürasyonu, contract test (Pact, Schemathesis), dokümantasyon (Redoc, Stoplight).

• Sözleşme önce avantaj: Frontend ve backend paralel çalışır, mock üzerinden entegrasyon 2-3 hafta önden ilerler.
• Sözleşme önce dezavantaj: Schema yazma disiplini yoksa “kod yazdık sonra dokümante ettik” haline döner — yarar kaybolur.
• Schema lint: Spectral, Vacuum gibi araçlar Microsoft/Google rehberlerini otomatik kontrol eder, PR’de gate yapılabilir.
• Breaking change tespiti: oasdiff aracı eski/yeni spec arasındaki breaking değişiklikleri tespit eder, CI’da merge engelleyici olarak kullanılır.

Kurumsal projelerde Ömer Önal olarak verdiğim API tasarımı danışmanlığında, üretim öncesi OpenAPI spec’i ekibin “tek kaynağı” olarak konumlandırmak, ileride 3-6 aylık entegrasyon hatalarını %40-60 aralığında azaltıyor. Tasarım disiplini için yazılım tasarım desenleri rehberini ekibin onboarding paketine eklemek; review sürecinde Spectral lint kurallarını CI’a entegre etmek; ve PR’da spec değişikliği gerekçesinin “neden” alanını zorunlu tutmak pratikte fark yaratıyor.

Anti-Pattern’ler: Üretimde Görülen 8 Yaygın Hata

Aşağıdaki anti-pattern’ler farklı sektörlerde gözlemlenen üretim sorunlarından derlendi. Hiçbiri “teorik” değil; her biri en az bir SEV-2 incident’a yol açmış kalıplardır.

1. “Tunnel POST”: Her şeyi POST ile yapmak (örn. POST /api ve body içinde {"action": "getUser"}). HTTP cache, log, gateway tüm semantiği kaybeder.
2. 200 OK + error body: Hata olduğunda 200 dönmek ama body’de {"success": false}. SDK ve monitoring kırılır.
3. Soft delete ile DELETE karışıklığı: DELETE çağrısı kaynağı gizliyor ama listede görünmeye devam ediyorsa açıkça archived_at alanı eklenmeli, semantik ayrı tutulmalı.
4. N+1 endpoint: İstemci her satır için ayrı endpoint çağırıyor. Bunun yerine batch endpoint veya ?include=lines,customer embedding.
5. Snake-case + camelCase karışımı: Aynı API’da order_id ve orderId yan yana — SDK kullanımı kâbus.
6. Pagination total count saplantısı: Her listede COUNT(*) sorgusu 1M satırlık tabloyu kilitler. Yaklaşık sayım veya materialized view ile çözülmeli.
7. Hatasız 500: Tüm exception’lar generic 500 dönüyor, hata kodu yok. RFC 9457 problem details ile çözülür.
8. Senkron uzun iş: 60+ saniyelik raporu HTTP isteğinde yapmak. 202 Accepted + job polling veya webhook callback gerekir.

Bu anti-pattern’lerin çoğu, takım büyürken servis sınırları net olmadığında ortaya çıkıyor. API kontratının iç implementasyondan bağımsızlaşması için, port/adapter ayrımı veren mimari yaklaşımlar ve Saga Pattern gibi dağıtık transaction kalıpları, REST yüzeyinde sızıntı oluşmadan iç refactoring’i mümkün kılar.

Performans, Caching ve Observability

HTTP caching, REST’in en güçlü ama en az kullanılan kozu. Cache-Control, ETag, If-None-Match, Last-Modified başlıkları doğru ayarlandığında, public CDN katmanı arkasında istek sayısının %60-90’ı origin’e gelmeden çözülebilir. Cloudflare 2024 trend raporuna göre cache hit oranı %85+ olan API’larda p95 latency 3-5x iyileşiyor.

Başlık	Amaç	Tipik değer	Ne zaman kullanılır
Cache-Control	Cache davranışı	public, max-age=300	Public, sık okunan kaynak
ETag	İçerik hash	"a1b2c3"	Optimistic concurrency + cache
If-Match	Conditional write	"a1b2c3"	PUT/PATCH, çakışma kontrol
If-None-Match	Conditional read	"a1b2c3"	GET, 304 dönüş için
Vary	Cache key parçası	Accept-Encoding	İçerik müzakeresi
X-Request-Id	Trace korelasyon	UUID v7	Tüm istek/yanıt

Observability tarafında OpenTelemetry Semantic Conventions for HTTP 2024’te stable oldu. http.request.method, http.response.status_code, url.template gibi standart attribute’lar sayesinde vendor lock-in olmadan tracing, metrics ve loglar bağlanabiliyor. Modern API’da minimum üç sinyal: latency histogram (p50/p95/p99), error rate (4xx/5xx ayrı), throughput (RPS endpoint başına). Bu sinyallerin alarm eşiklerini “endpoint başına” değil “müşteri tier’ı başına” çekmek ise SRE oyunkitabının daha olgun düzeyini temsil eder.

Asenkron iş akışları için 202 + polling pahalı olabilir; modern alternatif webhook + signed payload veya server-sent events (SSE). Distributed iş akışlarında uzun yaşam döngülü asenkron süreçlerin durumunu istemciye sızdırmadan yönetmek; UI-specific aggregation katmanları (mobil için ayrı, web için ayrı backend-for-frontend) tasarlamak; ve event-driven yan kanalları (örn. Kafka, EventBridge) REST kontratının yan ürünü olarak yayınlamak, REST katmanının üzerine bina edilen yaygın yapı taşlarıdır.

Sık Sorulan Sorular (SSS)

Sonuç

2026’da RESTful API tasarımı bir “doğru/yanlış” tartışması değil, operasyonel olgunluk meselesi. Karar çerçevesi şu sırayla işliyor: (1) Kaynak modelini domain sınırlarıyla hizala, (2) HTTP semantiğini katı uygula (idempotency, status code, RFC 9457 hata gövdesi), (3) OpenAPI 3.1 sözleşmesini ekibin tek kaynağı yap, (4) Sürümleme stratejisini erken sabitle ve dokümante et, (5) Caching + rate-limit + observability’yi ürünün ilk sürümünden itibaren kontrata dâhil et.

Bu beş adımı tamamlayan bir API, müşteri entegrasyon süresini haftalardan günlere düşürür; SDK üretimini, mock server’ı, contract test’i ücretsiz hediye olarak getirir. Bir adımı atlayan API ise 6-12 ay içinde “v2 migrasyonu” projesini kaçınılmaz hâle getirir — ki bu maliyet, baştan doğru kurmanın 5-10 katı.

Eğer mevcut bir REST API’sını yeniden tasarlamak, parallel run stratejisi kurmak veya OpenAPI tabanlı bir governance modeli oluşturmak istiyorsan iletişim sayfasından mevcut API kontratını ve hedef metrikleri (latency p95, error budget, müşteri sayısı) paylaşabilirsin; somut bir öncelik haritası çıkarmak için ilk değerlendirmeyi birlikte yapabiliriz.