Sağlam Bir REST API Nasıl Tasarlanır?

Bir API, uygulamanızın dış dünyaya açılan kapısıdır. İyi tasarlanmış bir API'yi kullanan geliştirici, belgelere bakmadan bir sonraki uç noktanın (endpoint) nasıl görüneceğini tahmin edebilir. Kötü tasarlanmış bir API ise her adımda sürpriz çıkarır, sürekli belge karıştırmayı gerektirir ve zamanla bakımı kâbusa döner. REST, bu tahmin edilebilirliği sağlamak için ortak bir dil sunar. Bu yazıda sağlam bir REST API'nin temel ilkelerini topladık.

Kaynaklar isimdir, fiil değil

REST'in kalbinde "kaynak" (resource) kavramı vardır: kullanıcılar, projeler, siparişler... Uç nokta adresleriniz bu kaynakları isim olarak, çoğul hâlde tanımlamalı; eylemi ise HTTP metodu belirtmeli.

Kötü:

GET  /getAllProjects
POST /createNewProject
GET  /deleteProject?id=5

İyi:

GET    /api/projeler          → tüm projeleri listele
POST   /api/projeler          → yeni proje oluştur
GET    /api/projeler/5        → 5 numaralı projeyi getir
PUT    /api/projeler/5        → 5 numaralı projeyi güncelle
DELETE /api/projeler/5        → 5 numaralı projeyi sil

Dikkat edin: adres aynı kalıyor, niyeti metot taşıyor. Bu tutarlılık, API'yi öğrenmeyi kökten kolaylaştırır.

HTTP metotlarını doğru kullanın

Her metodun bir anlamı ve beklenen bir davranışı vardır:

• GET — Veri okur, hiçbir şeyi değiştirmez. Defalarca çağrılabilir (güvenli).
• POST — Yeni bir kaynak oluşturur.
• PUT — Bir kaynağı tümüyle günceller/yerine koyar.
• PATCH — Bir kaynağın yalnızca bazı alanlarını günceller.
• DELETE — Kaynağı siler.

GET isteğinin veride değişiklik yapmaması özellikle önemlidir; arama motorları ve önbellekler GET'i serbestçe tekrarlayabileceğini varsayar.

Durum kodları gerçek bir dildir

Her yanıtta 200 OK dönmek yaygın ama yanlış bir alışkanlıktır. HTTP durum kodları, istemcinin gövdeyi okumadan ne olduğunu anlamasını sağlar:

• 200 OK — İstek başarılı.
• 201 Created — Yeni kaynak oluşturuldu (POST sonrası).
• 204 No Content — Başarılı ama dönecek gövde yok (DELETE sonrası).
• 400 Bad Request — İstemci hatalı veri gönderdi.
• 401 Unauthorized — Kimlik doğrulama gerekli.
• 403 Forbidden — Kimlik var ama yetki yok.
• 404 Not Found — Kaynak bulunamadı.
• 409 Conflict — Çakışma (örneğin zaten var olan bir kayıt).
• 500 Internal Server Error — Sunucu tarafında beklenmeyen hata.

Genel kural: 4xx "sen yanlış yaptın", 5xx "ben yanlış yaptım" demektir.

Tutarlı ve açıklayıcı hata yanıtları

Bir hata oluştuğunda istemciye yalnızca durum kodu değil, anlaşılır bir gövde de dönün. Tüm hatalarınızın aynı yapıda olması, istemci tarafında tek bir yerden ele alınmasını sağlar:

{
  "hata": {
    "kod": "GECERSIZ_EPOSTA",
    "mesaj": "Girilen e-posta adresi geçerli değil.",
    "alan": "email"
  }
}

"Bir şeyler ters gitti" gibi mesajlar yerine, hatanın hangi alandan kaynaklandığını ve nasıl düzeltileceğini söyleyin.

Sayfalama, filtreleme ve sıralama

Bir liste uç noktası binlerce kaydı tek seferde döndürmemeli. Bu işleri sorgu parametreleriyle yapın:

GET /api/projeler?sayfa=2&limit=20&sirala=-tarih&kategori=web

• sayfa ve limit ile sayfalama,
• sirala=-tarih ile tarihe göre azalan sıralama (önündeki - "azalan" anlamına gelir),
• kategori=web ile filtreleme.

Yanıtta toplam kayıt sayısını da döndürün ki istemci kaç sayfa olduğunu bilebilsin.

Sürümleme: geleceği bozmadan değişmek

API'niz büyüdükçe değişecektir. Mevcut kullanıcıları kırmadan değişiklik yapabilmek için en baştan sürümleyin:

/api/v1/projeler

Geriye dönük uyumsuz bir değişiklik gerektiğinde v2 çıkarır, v1'i bir süre daha çalışır tutarsınız. Böylece istemciler kendi hızlarında geçiş yapar.

Güvenliğin temel kuralları

• Her zaman HTTPS kullanın; düz HTTP üzerinden token veya şifre taşımayın.
• Kimlik doğrulama için oturum çerezleri veya token (örneğin JWT) kullanın; kimliği her istekte sunucu tarafında doğrulayın.
• İstemciden gelen her veriyi doğrulayın; "istemci nasılsa kontrol etti" varsayımı en yaygın güvenlik açığının kaynağıdır.
• Kötüye kullanımı önlemek için istek sınırlandırma (rate limiting) uygulayın.

Sonuç

İyi bir REST API'nin sırrı zekice numaralarda değil, tutarlılıkta saklıdır: kaynakları isimle adlandırmak, metotları amacına uygun kullanmak, doğru durum kodlarını döndürmek ve hataları öngörülebilir bir biçimde sunmak. Bu ilkelere sadık kaldığınızda, API'nizi kullanan geliştirici —ki çoğu zaman gelecekteki sizsinizdir— belgelere değil sezgisine güvenerek ilerleyebilir. Tahmin edilebilir bir API, en iyi belgelendirilmiş API'den bile keyiflidir.