RESTful API URL Tasarımı: Developer-Friendly Endpoint Rehberi

RESTful API endpoint tasarımı için en iyi uygulamalar. Temiz, tutarlı ve ölçeklenebilir API URL yapıları oluşturun.

RESTful API tasarımında URL yapısı, API'nizin kullanılabilirliğini ve bakım kolaylığını doğrudan etkiler. Bu rehberde developer-friendly API endpoint'leri tasarlamayı öğreniyoruz.

REST Temelleri

REST Nedir?

Representational State Transfer (REST), web API'leri için bir mimari stildir. Kaynakları (resources) URL'lerle temsil eder ve HTTP metodlarını kullanır.

HTTP Metodları

GET    → Kaynak okuma (Read)
POST   → Yeni kaynak oluşturma (Create)
PUT    → Kaynağı tamamen güncelleme (Replace)
PATCH  → Kaynağı kısmen güncelleme (Partial Update)
DELETE → Kaynak silme (Delete)

URL Tasarım Prensipleri

1. İsim Kullanın, Fiil Değil

# YANLIŞ - Fiil kullanımı
GET  /getUsers
POST /createUser
PUT  /updateUser/123
DELETE /deleteUser/123

# DOĞRU - İsim kullanımı
GET    /users        → Tüm kullanıcıları getir
GET    /users/123    → Tek kullanıcı getir
POST   /users        → Yeni kullanıcı oluştur
PUT    /users/123    → Kullanıcıyı güncelle
DELETE /users/123    → Kullanıcıyı sil

2. Çoğul İsim Kullanın

# YANLIŞ
/user
/product
/order

# DOĞRU
/users
/products
/orders

3. Hiyerarşik Yapı

# Kullanıcının siparişleri
GET /users/123/orders

# Siparişin ürünleri
GET /orders/456/items

# Kullanıcının belirli siparişi
GET /users/123/orders/456

4. Küçük Harf ve Tire Kullanın

# YANLIŞ
/userProfiles
/User_Profiles
/USER-PROFILES

# DOĞRU
/user-profiles

Versiyonlama

URL'de Versiyon

# En yaygın yöntem
https://api.example.com/v1/users
https://api.example.com/v2/users

Header'da Versiyon

GET /users
Headers:
  Accept: application/vnd.example.v1+json
  Accept: application/vnd.example.v2+json

Query Parameter'da Versiyon

GET /users?version=1
GET /users?version=2

Filtreleme, Sıralama ve Pagination

Filtreleme

# Basit filtreleme
GET /products?category=electronics
GET /products?category=electronics&brand=apple

# Karşılaştırma operatörleri
GET /products?price[gte]=100&price[lte]=500
GET /products?price_min=100&price_max=500

# Arama
GET /products?search=iphone
GET /users?q=john

Sıralama

# Tek alan sıralama
GET /products?sort=price
GET /products?sort=-price        # Azalan
GET /products?sort=price&order=desc

# Çoklu alan sıralama
GET /products?sort=category,-price
GET /products?sort_by=category,price&order=asc,desc

Pagination

# Offset-based
GET /products?page=2&per_page=20
GET /products?offset=20&limit=20

# Cursor-based (daha performanslı)
GET /products?cursor=abc123&limit=20

# Response headers
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: </products?page=3>; rel="next", </products?page=1>; rel="prev"

Alt Kaynak İlişkileri

Nested Resources

# Bir kullanıcının blog yazıları
GET /users/123/posts
POST /users/123/posts
GET /users/123/posts/456

# Maksimum 2-3 seviye derinlik
GET /users/123/posts/456/comments  # OK
GET /users/123/posts/456/comments/789/likes  # Çok derin!

Flat vs Nested

# Nested - İlişki vurgulu
GET /users/123/orders

# Flat - Daha esnek
GET /orders?user_id=123

# Her ikisi de geçerli, kullanım senaryosuna göre seçin

Özel Endpoint'ler

Actions (İşlemler)

# Kaynak üzerinde özel işlemler
POST /users/123/activate
POST /users/123/deactivate
POST /orders/456/cancel
POST /payments/789/refund

# Alternatif: PATCH ile durum güncelleme
PATCH /users/123
{ "status": "active" }

PATCH /orders/456
{ "status": "cancelled" }

Batch Operations

# Toplu silme
DELETE /users?ids=1,2,3,4,5

# Toplu güncelleme
PATCH /users/batch
[
  { "id": 1, "status": "active" },
  { "id": 2, "status": "inactive" }
]

Search Endpoint

# Karmaşık arama için özel endpoint
POST /search/products
{
  "query": "laptop",
  "filters": {
    "category": "electronics",
    "price_range": [500, 2000]
  },
  "sort": { "field": "relevance", "order": "desc" }
}

Response Formatı

Başarılı Response

# Tek kaynak
GET /users/123
{
  "id": 123,
  "name": "Ahmet Yılmaz",
  "email": "ahmet@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

# Liste
GET /users
{
  "data": [
    { "id": 1, "name": "Ahmet" },
    { "id": 2, "name": "Mehmet" }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

Hata Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Doğrulama hatası",
    "details": [
      {
        "field": "email",
        "message": "Geçersiz email formatı"
      }
    ]
  }
}

HTTP Durum Kodları

# Başarı
200 OK           → GET, PUT, PATCH başarılı
201 Created      → POST başarılı, yeni kaynak oluşturuldu
204 No Content   → DELETE başarılı

# Client Hataları
400 Bad Request  → Geçersiz istek
401 Unauthorized → Kimlik doğrulama gerekli
403 Forbidden    → Yetki yok
404 Not Found    → Kaynak bulunamadı
409 Conflict     → Çakışma (duplicate vb.)
422 Unprocessable→ Doğrulama hatası
429 Too Many Req → Rate limit aşıldı

# Server Hataları
500 Internal     → Sunucu hatası
503 Unavailable  → Servis kullanılamıyor

URL Güvenliği

Hassas Bilgi Gizleme

# YANLIŞ - Hassas bilgi URL'de
GET /users?api_key=secret123
GET /auth?password=mypass

# DOĞRU - Header'da
Authorization: Bearer token123
X-API-Key: secret123

ID Gizleme

# Sequential ID yerine UUID
GET /users/550e8400-e29b-41d4-a716-446655440000

# Veya hash ID
GET /users/a1b2c3d4

Gerçek Dünya Örnekleri

E-ticaret API

# Ürünler
GET    /products
GET    /products/:id
GET    /products/:id/reviews
GET    /categories/:id/products

# Sepet
GET    /cart
POST   /cart/items
PUT    /cart/items/:id
DELETE /cart/items/:id

# Siparişler
GET    /orders
POST   /orders
GET    /orders/:id
POST   /orders/:id/cancel

Sosyal Medya API

# Kullanıcılar
GET    /users/:username
GET    /users/:id/followers
GET    /users/:id/following
POST   /users/:id/follow
DELETE /users/:id/follow

# Postlar
GET    /posts
GET    /posts/:id
POST   /posts/:id/like
DELETE /posts/:id/like
GET    /posts/:id/comments
POST   /posts/:id/comments

Sonuç

İyi tasarlanmış API URL'leri, API'nizin kullanılabilirliğini artırır ve bakımını kolaylaştırır. Tutarlı isimlendirme, mantıklı hiyerarşi ve standart HTTP metodları kullanarak developer-friendly API'ler oluşturun. SlugURL gibi araçlarla web URL'lerinizi optimize ettiğiniz gibi, API endpoint'lerinizi de aynı özenle tasarlayın.