REST API tasarımında kaynak (resource) isimlendirme ve URL yapısı nasıl olmalıdır?

REST'te URL kaynağı (isim) belirtir, yapılacak işlemi ise HTTP metodu belirtir.

Temel kurallar

• İsim kullanın, fiil kullanmayın: /users, /getUsers değil.
• Koleksiyonlar için çoğul: /orders, /orders/42.
• İlişkiler için hiyerarşi: /users/42/orders. İki seviyeden derine inmekten kaçının.
• Küçük harf ve tire: /order-items (kebab-case).
• Filtre, sıralama ve sayfalama query string'de: /orders?status=paid&sort=-created_at&limit=20.
• Sonda / ve dosya uzantısı (.json) yok; format Accept başlığıyla belirlenir.

Metot ve URL eşleşmesi

CRUD'a uymayan işlemler

Durum değişikliğini alt kaynak olarak modelleyin:

POST /orders/42/cancellation
POST /orders/42/refunds

Bu mümkün değilse pragmatik bir aksiyon ucu kabul edilebilir (POST /orders/42/cancel), ama tutarlı olun.

Tutarlılık

Hata yanıtları için tek bir format (ör. RFC 9457 Problem Details: type, title, status, detail), JSON alanlarında tek bir isimlendirme stili (camelCase veya snake_case) ve tarihler için ISO 8601 kullanın.