Kaynak odaklı REST

REST (Representational State Transfer), Roy Fielding'in doktora tezinde tanimlanan bir mimari stildir ve HTTP uzerinde ölçeklenebilir web servisleri tasarlamak icin en yaygın cercevelerden biridir. REST'in ozu, sistemi kaynaklar etrafinda modellemektir: müşteri, siparis, ürün, fatura gibi varliklar URI ile tanimlanir; istemci bu kaynaklarin temsillerini HTTP fiilleriyle okur veya degistirir. Kaynak odaklı düşünce, RPC tarzindaki fiil-merkezli endpoint'lerden (/createOrder, /getUserById) bilincli olarak ayrilir. Bu ayrim, API'nin ongorulebilirligini artirir, cache stratejilerini basitlestirir ve çoklu istemci ekiplerinin ayni sozlesmeyi ogrenmesini kolaylastirir. Kaynak odaklı tasarım ayrica altyapi ekiplerinin rate limiting, gozlemlenebilirlik ve güvenlik politikalari uygulamasini standartlastirir.

Kaynak kavrami ve temsil

Kaynak, sistemin adreslenebilir bir varligidir. Teknik olarak her kaynak en az bir URI ile tanimlanir. Kaynak soyut olabilir: oturum, arama sonucu, rapor ciktisi, is kuyrugu durumu da geçerli kaynaklardir. Önemli olan, kaynagin durumunun temsili (representation) ile tasindigidir. JSON, XML, HAL+JSON veya CBOR gibi formatlar temsil bicimidir; kaynagin kendisi degildir. Ayni kaynak farklı temsillerle sunulabilir: Accept: application/json ile JSON, Accept: text/csv ile CSV. Content negotiation bu esnekligi sağlar. Kaynak tasarımında sik yapılan hata, veritabanı tablolarini birebir URI'ye kopyalamaktir. Domain modeli ile persistence modeli farklı olabilir. Örneğin siparis ve siparis kalemleri tek bir /orders/{id} kaynaginda birlestirilebilir veya ayri kaynaklar olarak sunulabilir; seçim istemci ihtiyacina, tutarlılık gereksinimlerine ve aggregate root sinirlarina baglidir.

Kaynak koleksiyonlari ve tekil kaynaklar farklı URI'lere sahiptir. Koleksiyon uzerinde filtreleme, siralama ve sayfalama query parametreleri ile yapilir; tekil kaynak uzerinde CRUD islemleri HTTP fiilleri ile yurutulur. Alt kaynaklar mantiksal iliskiyi yansitir: /customers/{id}/orders müşteriye ait siparisleri listeler. Ancak asiri ic ice URI kirilgan olabilir; müşteri silindiginde alt path'lerin anlami belirsizlesir. Bu durumda bağlantı URI'leri (links alani) ile ilişkiler HATEOAS ile ifade edilebilir.

URI tasarım ilkeleri

Iyi bir REST URI su ozelliklere sahiptir: cogul isimler (/products), hiyerarsi ile mantıklı ilişki (/customers/{id}/orders), küçük harf ve tire ile okunabilirlik (/order-items), path segmentlerinde fiil olmamasi. Asagidaki matris tipik kaynak yuzeyini gösterir:

GET    /api/v1/products
GET    /api/v1/products/{productId}
POST   /api/v1/products
PUT    /api/v1/products/{productId}
PATCH  /api/v1/products/{productId}
DELETE /api/v1/products/{productId}

URI tasarımında versiyon segmenti (/v1/) veya header tabanli versiyonlama ayri bir konudur; kaynak isimleri versiyonlar arasinda mümkün oldugunca sabit kalmalidir. Query parametreleri arama, filtreleme ve projeksiyon icin kullanılır: GET /products?category=electronics&fields=id,name,price. Sparse fieldsets bant genisligi tasarrufu sağlar. URI uzunlugu pratik limitler icinde tutulmali; cok uzun filtre listeleri POST ile arama kaynagina (/product-searches) taşınabilir.

HTTP fiilleri ve semantik

HTTP metodu kaynak uzerindeki islemin niyetini tasir. Doğru eslestirme REST uyumlulugunun temelidir:

• GET: Güvenli ve idempotent. Yan etki uretmemeli, cache'lenebilir.
• HEAD: GET ile ayni ama govdesiz; metadata ve cache dogrulama icin.
• POST: Yeni kaynak oluşturma veya işlem tetikleme. Idempotent degildir.
• PUT: Tam kaynak değiştirme veya upsert. Idempotent.
• PATCH: Kismi güncelleme. JSON Patch (RFC 6902) veya Merge Patch (RFC 7386) ile.
• DELETE: Kaynak silme. Idempotent (ikinci silme 404 veya 204).

GET ile veri silmek veya POST ile salt okuma yapmak HTTP semantigini bozar, ara katman cache'lerini devre disi birakir ve güvenlik denetimlerini zorlastirir. Işlem gerektiren durumlarda alt kaynak dusunulebilir: POST /orders/{id}/cancel tartismali ama pratik bir uzlasimdir; alternatif PATCH ile durum alani guncellemesidir. Güvenli metotlar sunucu durumunu degistirmez. Idempotent metotlarda ayni istek tekrarlandiginda sonuç ayni kalir. Ag timeout ve retry senaryolarinda bu ayrim kritiktir.

Durum kodlari ve anlamli yanitlar

REST API'ler HTTP durum kodlarini anlamli kullanmalidir:

1. 200 OK: Başarılı GET, PUT, PATCH; govde ile temsil doner.
2. 201 Created: POST ile kaynak oluşturma; Location header zorunludur.
3. 204 No Content: DELETE veya govdesiz başarılı yanıt.
4. 304 Not Modified: Conditional GET cache hit.
5. 400 Bad Request: Istemci hatasi, malformed JSON.
6. 401 Unauthorized: Kimlik dogrulama eksik.
7. 403 Forbidden: Kimlik var ama yetki yok.
8. 404 Not Found: Kaynak yok.
9. 409 Conflict: Is kurali catismasi, optimistic lock.
10. 412 Precondition Failed: ETag uyusmazligi.
11. 422 Unprocessable Entity: Semantik dogrulama hatasi.
12. 429 Too Many Requests: Rate limit.

Her başarılı yanıt tutarlı bir govde semasi tasimalidir. Liste yanitlarinda items, links gibi alanlar standartlastirilir. Hata yanitlari ayri bir sözleşme ile tanimlanir; başarı ve hata semalari karistirilmamali.

HATEOAS ve hypermedia

HATEOAS (Hypermedia as the Engine of Application State), istemcinin sunucunun sagladigi linklerle ilerlemesini onerir:

{
  "id": "ord-42",
  "status": "pending",
  "_links": {
    "self": { "href": "/orders/ord-42" },
    "cancel": { "href": "/orders/ord-42/cancel", "method": "POST" },
    "pay": { "href": "/payments", "method": "POST", "templated": false }
  }
}

Tüm API'lerde HATEOAS zorunlu degildir; mobil ve SPA istemcileri genelde sabit endpoint sozlesmesi tercih eder. Ancak uzun omurlu entegrasyonlarda link tabanli kesif, endpoint degisikliklerinde istemci kirilmalarini azaltabilir. HAL, JSON:API ve Siren gibi hypermedia formatlari link semantigini standartlastirir.

ETag, concurrency ve cache

Optimistic concurrency icin ETag ve If-Match header'lari kullanılır. GET yanitinda ETag: "v3" doner; PUT/PATCH istemcisi If-Match: "v3" gonderir. Versiyon uyusmazliginda 412 Precondition Failed donulur. Weak ETag (W/"...") byte-level degil semantik esitlik icin kullanılır. GET yanitlarinda Cache-Control, Last-Modified ve conditional request (If-None-Match, If-Modified-Since) bant genisligi tasarrufu sağlar. Özel veri icin private, no-store kullanılır. Paylasilan cache (CDN) icin s-maxage dikkatle ayarlanir; kullanıcıya özel listeler cache'lenmemelidir.

Richardson olgunluk modeli

Leonard Richardson REST olgunlugunu dört seviyede tanimlar: Seviye 0 tek URI ve POST ile tunel; Seviye 1 kaynak basina ayri URI; Seviye 2 HTTP fiillerinin doğru kullanımı; Seviye 3 HATEOAS ile hypermedia. Pratik kurumsal projeler cogunlukla Seviye 2'de kalir ve bu çoğu kullanım senaryosu icin yeterlidir. Seviye 3 public platform API'lerinde ve uzun omurlu B2B entegrasyonlarda deger üretir. Olgunluk seviyesi bilincli secilmeli; HATEOAS eklemek sadece checklist icin yapilmamali.

Güvenlik ve kaynak yetkilendirme

Yetkilendirme kaynak ve eylem bazinda dusunulmelidir. OAuth 2.0 scope'lari kaynak gruplariyla eslestirilebilir: orders:read, orders:write. Her endpoint icin hangi scope'un gerekli olduğu dokumante edilmeli. Row-level security gerektiren kaynaklarda liste endpoint'i yalnizca yetkili kayitlari donmeli; filtre parametresi ile yetki bypass edilememeli. Rate limiting kaynak bazinda veya tenant bazinda uygulanabilir.

Anti-kaliplar ve duzeltme yollari

• RPC REST: Tüm işlemler POST ile fiil path'lerinde. Çözüm: kaynak ve HTTP fiili yeniden modelleme.
• GET ile mutation: Cache zehirlenmesi ve CSRF riski. Çözüm: POST/PATCH/DELETE kullanımı.
• Session state in URL: /api?sessionId=abc kaynak tasarımı yerine geçici parametreler. Çözüm: header veya cookie ile oturum.
• 200 ile her sey: Hata durumlari bile 200 OK. Çözüm: anlamli status kodlari.
• Asiri ic ice URI: Bes seviye derinlik. Çözüm: duz koleksiyon + filtre veya link.

Medya tipi ve içerik pazarligi

Content-Type ve Accept header'lari temsil formatini belirler. API varsayilan olarak JSON sunabilir ancak CSV export veya PDF rapor gibi alternatif temsiller ayri medya tipi ile desteklenir. 406 Not Acceptable istemcinin istedigi format sunulamadiginda donulur. Versiyonlama bazen medya tipi uzerinden yapilir: application/vnd.company.product.v2+json. Bu yaklaşım URI'yi temiz tutar ancak cache ve dokumantasyon karmasikligini artirir.

Test, sözleşme ve gozlemlenebilirlik

REST API testleri uc katmanda dusunulur: contract test (OpenAPI semasina uyum), entegrasyon test (gerçek HTTP istekleri), property-based test (idempotency ve cache davranisi). Consumer-driven contract (Pact) ile kirici değişiklikler erken yakalanir. Kaynak odaklı tasarım test senaryolarini netlestirir: her kaynak icin CRUD matrisi yazilir. Distributed tracing ile her istekte traceparent header'i tasinar; kaynak URI ve HTTP metodu span attribute olarak loglanir. Metrikler endpoint bazinda latency ve hata orani raporlar.

Özet

Kaynak odaklı REST, API'yi adreslenebilir varliklar ve HTTP semantigi uzerine insa eder. URI'ler cogul ve fiilsiz, metotlar anlamli, durum kodlari tutarlı olmalidir. HATEOAS, ETag ve cache header'lari olgun API'lerin ayrilmaz parcasidir. RPC aliskanliklarindan kacinmak, Richardson modelinde hedef seviyeyi bilincli secmek ve dokumante edilmis filtre ile sayfalama sürdürülebilir REST API'nin temelidir.

Kaynak yaşam dongusu ve durum makineleri

Bircok kaynak pasif CRUD'dan ote bir durum makinesi ile modellenir. Siparis kaynagi draft, confirmed, shipped, delivered gibi durumlar tasir. Geçerli gecisler API sozlesmesinde açık olmalidir; gecersiz geçiş 409 Conflict ile reddedilir. Durum guncellemesi icin PATCH tercih edilir; her geçiş ayri alt kaynak olarak modellenebilir ancak bu URI sayisini artirir. Istemciye hangi gecislerin mümkün olduğu HATEOAS linkleri veya ayri allowedTransitions alani ile bildirilebilir. Zamanlanmis gecisler (örneğin otomatik iptal) arka plan isleri ile yurutulur; API yalnizca güncel durumu yansitir.

Kaynak oluşturma POST ile yapildiginda sunucu tarafli ID uretimi tercih edilir. Istemci tarafli ID (UUID) idempotency ve offline-first senaryolarda kullanılır. Oluşturma yanitinda 201 Created ve Location header istemcinin yeni kaynaga erismesini sağlar. Partial representation donmek bant genisligi acisindan avantajli olabilir; tam temsil varsayilan kalmalidir.

Cok kiracili sistemlerde kaynak izolasyonu

SaaS API'lerde tenant kimligi URL'de (/tenants/{tid}/orders) veya JWT claim'inde taşınabilir. URL'de tenant acikligi debug kolayligi sağlar; claim tabanli yaklaşım URL'yi sade tutar. Her iki durumda da yetkilendirme katmanı tenant sinirini zorunlu kilmalidir. Capraz tenant erisimi en kritik güvenlik ihlallerinden biridir ve otomatik testlerle sürekli dogrulanmalidir.