REST API Tasarımı

REST API tasarımı, kaynakları ve bu kaynaklar üzerindeki HTTP davranışını istemci açısından öngörülebilir bir sözleşmeye dönüştürür. URL'yi yalnızca controller yolu olarak değil; kaynak kimliği, durum kodu, hata modeli, cache ve evrim politikasıyla birlikte tasarlamak gerekir.

Hızlı Karar

İhtiyaç	Başlangıç kararı	Dikkat
Kaynak koleksiyonu	Çoğul isimli URI (/users)	Fiil içeren URI'lerden kaçın
Tek kaynak işlemi	HTTP metodu + kaynak kimliği	Idempotency davranışını yaz
Büyük liste	Cursor veya keyset pagination	Sıralama anahtarı sabit olmalı
Karmaşık arama	Query parametreleri veya ayrı search endpoint'i	Serbest SQL ifadesi kabul etme
Kısmi güncelleme	PATCH ve açık merge semantiği	Null ile alan silme ayrımı net olmalı

Üretim Kontrol Listesi

• Problem: Kaynaklar, alt kaynaklar ve aggregate sınırları açık mı?
• Çözüm: Metot, durum kodu, hata gövdesi, pagination ve filtre sözleşmesi tanımlı mı?
• Trade-off: REST sadelik ve HTTP tooling sağlar; çok karmaşık ekranlarda BFF veya GraphQL gerekebilir.
• Hata durumu: Validation, authorization, conflict, timeout ve rate-limit cevapları birbirinden ayrılmalı.
• Ölçüm: p95 latency, payload boyutu, sayfa derinliği, 4xx/5xx ve cache hit oranı izlenmeli.
• Güvenlik/maliyet: Filtre alanları allowlist ile sınırlandırılmalı; büyük response ve pahalı sorgular quota ile korunmalı.

Kaynak Modelleme

• Koleksiyon için /orders, tek kaynak için /orders/{orderId} kullan.
• İlişki gerçekten kaynak yaşam döngüsünün parçasıysa /orders/{id}/items; bağımsız sorgulanıyorsa /items?orderId={id} tercih et.
• URI'ye create, get, delete gibi fiiller koyma; iş komutu kaynak modeliyle ifade edilemiyorsa açık bir action endpoint'i kullan.
• Kimlik formatı ve zaman alanlarının temsilini standartlaştır; response'ta kaynak metadata'sını ve versiyon bilgisini gerektiğinde taşı.

HTTP Metotları ve Durum Kodları

İşlem	Metot	Başarılı cevap	Önemli hata
Listeleme	GET /orders	200 OK	400, 401, 403
Tek kaynak	GET /orders/{id}	200 OK	404 Not Found
Oluşturma	POST /orders	201 Created + Location	409, 422
Tam güncelleme	PUT /orders/{id}	200 veya 204	404, 409
Kısmi güncelleme	PATCH /orders/{id}	200 veya 204	400, 409
Silme	DELETE /orders/{id}	204 No Content	404, 409

202 Accepted, işin kuyruğa alındığını; 429 Too Many Requests, istemcinin daha sonra denemesi gerektiğini; 503 Service Unavailable, geçici kapasite veya dependency problemini anlatır. Hata gövdesi için status, stable error code, message, field errors, request/correlation ID ve gerekiyorsa retry bilgisi taşıyan tek bir format kullan.

Pagination, Filtering ve Sorting

Pagination seçenekleri

Model	Uygun olduğu durum	Bedel
Offset (page, size)	Küçük ve nispeten sabit listeler	Derin sayfalarda yavaşlar, ekleme/silmede kayma olur
Cursor	Sürekli değişen feed ve infinite scroll	Cursor opak ve süreli yönetilmelidir
Keyset	Büyük tablolar ve indeksli sıralama	Kullanıcı her alan üzerinden sayfalayamaz

Her liste cevabında stabil sort, limit, nextCursor veya hasMore semantiği tanımla. limit için üst sınır koy; default sıralamayı ve tie-breaker alanını (createdAt, id) açıkça yaz.

Filtreleme ve sıralama

status=active, createdAfter=... ve sort=-createdAt,name gibi allowlist edilmiş query parametreleri kullan. Alan adı ve yön serbest bırakılmamalı; filtre kombinasyonlarının sorgu planı, index ihtiyacı ve timeout bütçesi ölçülmelidir. Arama dili gerekiyorsa API'ye SQL veya ORM ifadesi geçmek yerine sınırlı bir arama sözleşmesi oluştur.

Bulk İşlemler ve HATEOAS

Bulk endpoint'lerinde her öğenin sonucu, hata kodu ve idempotency davranışı belirlenmelidir. Tek transaction ancak aynı consistency sınırında güvenliyse kullanılmalı; uzun bulk işleri 202 ve job status kaynağı döndürmelidir.

HATEOAS, response'a sadece URL eklemek değil, istemcinin geçerli sonraki aksiyonları keşfedebilmesidir:

{
  "id": "ord_123",
  "status": "pending",
  "_links": {
    "self": { "href": "/api/orders/ord_123" },
    "cancel": { "href": "/api/orders/ord_123/cancellation", "method": "POST" }
  }
}

Link relation adları, yetki ve mevcut durumla tutarlı olmalı; hiçbir link güvenlik kontrolünün yerine geçmemelidir.

OpenAPI ve API Performansı

OpenAPI sözleşmesi path, parameter, request/response schema, status code, security scheme ve örnekleri tanımlar. SpringDoc ile üretilen doküman, elle yazılan açıklamalar ve generated client aynı sözleşmeden beslenmelidir. OpenAPI ayrıntıları ve contract workflow için API Contract ve Tooling sayfasına bakılabilir.

Payload alanlarını gereksiz büyütme; field selection, compression, ETag/conditional request ve response cache'i ihtiyaca göre kullan. N+1 sorgu, pahalı sort ve sınırsız nested expansion API'nin HTTP seviyesinde görünmeyen darboğazlarıdır.

Uygulama Sonucu

İyi bir REST tasarımı; kaynak isimlerinden çok, başarılı ve hatalı akışların aynı istemci tarafından tekrar edilebilir olmasını sağlar. Her endpoint için örnek istek/yanıt, hata sözleşmesi, auth kapsamı, retry/idempotency ve pagination davranışı dokümante edilmelidir.