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.

Aynı isteğin iki kez gelmesi: idempotentlik

Ağ dünyasında istekler kaybolur, zaman aşımına uğrar ve istemciler tekrar dener. API'niz buna hazır olmalı. Bir işlem, kaç kez tekrarlanırsa tekrarlansın aynı sonucu üretiyorsa "idempotent"tir:

• GET, PUT ve DELETE doğaları gereği idempotent olmalıdır: aynı PUT /api/projeler/5 isteği iki kez gelirse kayıt yine aynı hâle gelir.
• POST ise tehlikelidir: "Sipariş oluştur" isteği iki kez işlenirse iki sipariş doğar.

Kritik POST uç noktaları için pratik çözüm, istemcinin ürettiği bir idempotency anahtarını kabul etmektir:

POST /api/siparisler
Idempotency-Key: 7f3b9c1a-...

Sunucu bu anahtarı bir süre saklar; aynı anahtarla ikinci istek geldiğinde işlemi tekrarlamak yerine ilk yanıtın aynısını döner. Ödeme ve kayıt gibi "iki kez olursa felaket" işlemlerinde bu desen sizi gece telefonlarından kurtarır.

Önbellek başlıkları: ETag ve Last-Modified

Sık okunan ama nadir değişen kaynaklarda, istemcinin her seferinde tüm gövdeyi indirmesi israftır. HTTP bunun için yerleşik bir mekanizma sunar:

# Sunucu yanıtı
ETag: "33a64df5"

# İstemcinin sonraki isteği
If-None-Match: "33a64df5"

İçerik değişmediyse sunucu gövdesiz bir 304 Not Modified döner; bant genişliği ve süre kazanılır. Express gibi çatılarda statik dosyalar için bu otomatiktir; kendi JSON uç noktalarınızda ise içeriğin özetinden (hash) bir ETag üretip karşılaştırmanız yeterlidir. Liste uç noktalarında Cache-Control: private, max-age=30 gibi kısa ömürlü bir önbellek bile algılanan hızı belirgin şekilde artırır.

API'nizi belgeleyin: OpenAPI

"İyi API belgeye gerek bırakmaz" ilkesi navigasyon için doğrudur ama alan adları, zorunlu parametreler ve hata kodları için belge şarttır. Endüstri standardı OpenAPI (Swagger) ile uç noktalarınızı tek bir YAML/JSON dosyasında tanımlarsınız:

/api/projeler/{id}:
  get:
    summary: Tek bir projeyi getirir
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    responses:
      "200": { description: Proje bulundu }
      "404": { description: Proje yok }

Bu tanımdan otomatik olarak etkileşimli bir test arayüzü (Swagger UI), istemci kodu ve doğrulama şeması üretilebilir. Belgeyi koddan ayrı bir Word dosyasında tutmak yerine depoda, kodun yanında sürümlemek, "belge eski kaldı" problemini kökünden çözer.

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.