API Tasarim Rehberi: RESTful ve Modern API Mimari

REST API Nedir?

REST (Representational State Transfer), web servisleri tasarlamak icin kullanilan bir mimari stildir. Roy Fielding tarafindan 2000 yilinda doktora tezinde tanimlanan REST, HTTP protokolu uzerine kurulu, kaynak odakli ve durumsuz (stateless) bir iletisim modeli sunar. 2026 yilinda REST, web API tasariminin hala en yaygin standardi olmaya devam etmektedir.

Iyi tasarlanmis bir REST API, gelistiricilerin kolayca anlayip kullanabilecegi, olceklenebilir ve bakilabilir bir arayuz sunar. Bu rehberde, profesyonel bir REST API tasarlamanin temel ilkelerini, en iyi uygulamalarini ve pratik orneklerini detayli sekilde ele alacagiz.

Kaynak (Resource) Odakli Endpoint Tasarimi

REST API'larda endpoint'ler, kaynaklari (resource) temsil eder. Iyi bir endpoint tasarimi icin asagidaki ilkelere uyun:

• Isim kullanin, fiil degil: /kullanicilar dogru, /kullanicilariGetir yanlis. Eylem, HTTP metodu ile belirtilir.
• Cogul isimler kullanin: /urunler, /siparisler, /kullanicilar. Tutarlilik saglar.
• Hiyerarsik yapiyi yansistin: /kullanicilar/123/siparisler — 123 numarali kullanicinin siparisleri. Ikiden fazla ic ice gecmeyi (nesting) genellikle tercih etmeyin.
• Kucuk harf ve tire kullanin: /blog-yazilari seklinde. Alt cizgi veya camelCase kullanmayin.
• URL sonundaki egiik cizgi tutarli olsun: Ya tum endpoint'lerde kullanin ya da hicbirinde. Yonlendirme ile tutarlilik saglayin.
• Dosya uzantisi eklemeyin: /kullanicilar.json yerine, Accept basligiyla icerik turunu belirtin.

HTTP Metotlari ve Anllamlari

HTTP metotlari, kaynak uzerinde yapilacak islemi belirler. Her metodun ozel bir anlami ve davranisi vardir:

Idempotentbir islem, ayni istegi birden fazla kez gonderdiginizde ayni sonucu verir. GET, PUT ve DELETE idempotent'tir; POST degildir. Bu kavram, yeniden deneme (retry) mekanizmalari tasarlarken onemlidir.

HTTP Durum Kodlari

Dogru durum kodlari, API tuketicilerine istegin sonucu hakkinda net bilgi verir. Anlamli ve tutarli durum kodu kullanimi, hata ayiklamayi ve entegrasyonu kolaylastirir.

• 200 OK: Basarili GET, PUT veya PATCH istegi.
• 201 Created: Basarili POST istegi; yeni kaynak olusturuldu. Location basliginda yeni kaynagin URL'ini dondurun.
• 204 No Content: Basarili DELETE istegi; yanit govdesi yok.
• 400 Bad Request: Gecersiz istek; eksik veya hatali parametreler. Detayli hata mesaji dondurun.
• 401 Unauthorized: Kimlik dogrulaama yapilmamis veya basarisiz.
• 403 Forbidden: Kimlik dogrulanmis ama yetkisi yok.
• 404 Not Found: Istenen kaynak bulunamadi.
• 409 Conflict: Kaynak catismasi; ornegin zaten var olan bir e-posta ile kayit denemesi.
• 422 Unprocessable Entity: Dogrulama hatasi; istek yapisi dogru ama icerik gecersiz.
• 429 Too Many Requests: Istek limiti asildi (rate limiting).
• 500 Internal Server Error: Sunucu hatasi; istemcinin hatasi degil.

API Surumleme (Versioning)

API'niz zamanla evrilesecektir. Geriye donuk uyumsuz degisiklikler yaptiginizda, mevcut tuketicileri bozmamaniz gerekir. Surumleme stratejileri sunlardir:

• URL yolu ile: /api/v1/urunler, /api/v2/urunler. En yaygin ve en anlasilir yontemdir.
• Baslik ile: Accept: application/vnd.megis.v2+json. URL'i temiz tutar ancak kesif edilebilirligi azaltir.
• Sorgu parametresi ile: /urunler?version=2. Basit ama onbellek sorunlarina yol acabilir.

Hangi yontemi secerseniz secin, eski surumleri hemen kaldirmayin. Kullanicilara yeterli gecis suresi taniyin ve surum sonlandirma politikanizi acikca belgeleyin. Genellikle bir onceki surumu en az 6-12 ay desteklenmek iyi bir pratiktir.

Sayfalama (Pagination)

Buyuk veri kumeleri donduren endpoint'lerde sayfalama zorunludur. Tek seferde binlerce kayit dondurrmek hem sunucu hem de istemci performansini olumsuz etkiler.

• Offset-based: ?page=2&limit=20. Basit ve anlasilir. Buyuk veri kumelerinde performans sorunu yasanabilir cunku veritabani her seferinde offset kadar kaydi atlamak zorundadir.
• Cursor-based: ?cursor=abc123&limit=20. Bir onceki sayfanin son elemaninin kimligini kullanir. Buyuk veri kumelerinde cok daha performanslidir ve gercek zamanli veri eklenmesinden etkilenmez.
• Keyset-based: Cursor-based'e benzer; siralanmis bir alanin degerini filtre olarak kullanir.

Sayfalama yanitinda asagidaki meta verileri ekleyin: toplam kayit sayisi, mevcut sayfa, sayfa basi kayit sayisi, toplam sayfa sayisi, sonraki ve onceki sayfa baglantilari. HATEOAS ilkesine uygun olarak baglantilari yanit icerisinde saglamak, API kullanimini kolaylastirir.

Filtreleme, Siralama ve Arama

API tuketicilerinin verileri esnek sekilde sorgulamasini saglamak icin filtreleme, siralama ve arama yetenekleri ekleyin:

• Filtreleme: Sorgu parametreleri ile. /urunler?kategori=elektronik&fiyat_min=100&fiyat_max=500
• Siralama: /urunler?sort=fiyat&order=asc veya /urunler?sort=-fiyat (eksi isareti azalan siralama).
• Arama: /urunler?q=laptop. Tam metin arama icin ozel bir parametre kullanin.
• Alan secimi (Field Selection): /urunler?fields=isim,fiyat,stok. Gereksiz veri transferini azaltir.

Kimlik Dogrulama ve Yetkilendirme

API guvenliginin iki temel bileseni kimlik dogrulama (authentication) ve yetkilendirme (authorization) dir:

• API Key: Basit senaryolar icin. Baslikta veya sorgu parametresinde gonderilir. Guvenlik duzeyi dusuktur; genellikle sunucudan sunucuya iletisimde tercih edilir.
• JWT (JSON Web Token): Durumsuz kimlik dogrulama icin. Access token kisa omurlu (15 dakika), refresh token uzun omurlu (7 gun) olmalidir.
• OAuth 2.0: Ucuncu parti erisim yetkilendirmesi icin standart protokol. Authorization Code Flow, PKCE ile birlikte en guvenli yontemdir.
• Bearer Token: Authorization: Bearer <token> basliginda gonderilir.

Token'lari her zaman HTTPS uzerinden iletin. Access token'lari localStorage yerine bellekte tutun. Refresh token'lari HttpOnly cookie icerisinde saklayin.

Hata Yonetimi

Tutarli ve bilgilendirici hata yanitlari, API kullanimini onemli olcude iyilestirir. Standart bir hata yanit formati tanimlayin:

• Hata kodu: Makine tarafindan okunabilir, benzersiz bir hata tanimlayicisi.
• Mesaj: Insan tarafindan okunabilir hata aciklamasi.
• Detaylar: Dogrulama hatalari icin alan bazinda hata listesi.
• Zaman damgasi: Hatanin olusstugu zaman.
• Izleme kimligi (Trace ID): Hata ayiklama icin benzersiz kimlik.

API Dokumantasyonu

Dokumante edilmemis bir API, kullanilmayan bir API'dir. Kapsamli ve guncel dokumantasyon, API'nizin benimsenmesini saglar:

• OpenAPI (Swagger): API sartnamesi icin standart format. Otomatik dokumantasyon, istemci kodu uretimi ve test araclarini destekler.
• Interaktif ornekler: Swagger UI veya Redoc ile kullanicilar API'yi dogrudan dokumantasyon uzerinden test edebilir.
• Baslarken rehberi: Ilk API cagrisi icin adim adim talimatllar ekleyin.
• Degisiklik gunlugu (Changelog): Her surumde yapilan degisiklikleri belgeleyin.

API Tasarim Kontrol Listesi

1. Kaynak odakli, tutarli ve sezgisel endpoint yapiisi olusturun.
2. HTTP metotlarini dogru ve tutarli sekilde kullanin.
3. Anlamli HTTP durum kodlari donduurun.
4. Surumleme stratejisi belirleyin ve uygulayin.
5. Buyuk veri kumeleri icin sayfalama uygulayin.
6. Filtreleme, siralama ve arama yetenekleri ekleyin.
7. Guvenli kimlik dogrulama ve yetkilendirme mekanizmasi kurun.
8. Rate limiting uygulayarak kotuye kullaniimi onleyin.
9. Tutarli hata yanit formati tanimlayin.
10. OpenAPI ile kapsamli dokumantasyon olusturun.

Sonuc:Iyi tasarlanmis bir REST API, yalnizca teknik bir arayuz degil, gelistirici deneyiminin (DX) bir yansimmasidir. Tutarli kurallar, acik dokumantasyon ve guvenlik en iyi uygulamalariyla API'niz, hem ic ekibiniz hem de dis entegrasyonlar icin guvenilir bir temel olusturur. API tasarimina yatirdiginiz zaman, uzun vadede gelistirme hizini ve urun kalitesini dogrudan arttirir.