API Nedir? RESTful API Tasarımı Rehberi

API Nedir?

API (Application Programming Interface - Uygulama Programlama Arayüzü), farklı yazılım uygulamalarının birbirleriyle iletişim kurmasını sağlayan bir arayüzdür. API'ler modern yazılım geliştirmenin temel yapı taşlarıdır ve 2026'da neredeyse her dijital hizmet API'ler aracılığıyla çalışmaktadır.

Basit bir benzetmeyle: bir restoranda garson, mutfak ile sizin aranızdaki iletişimi sağlar. API de yazılımlar arasında aynı görevi üstlenir; bir uygulamanın sunduğu hizmetlere başka uygulamaların erişmesini mümkün kılar.

REST Nedir?

REST (Representational State Transfer), Roy Fielding tarafından 2000 yılında tanımlanan bir mimari stildir. RESTful API'ler, HTTP protokolü üzerinden çalışan, kaynak odaklı ve durumsuz (stateless) API'lerdir. Basitliği ve ölçeklenebilirliği sayesinde en yaygın kullanılan API mimarisi olmuştur.

RESTful API Temel Prensipleri

1. İstemci-Sunucu Ayrımı

İstemci (client) ve sunucu (server) birbirinden bağımsız çalışır. İstemci kullanıcı arayüzüyle, sunucu veri yönetimi ve iş mantığıyla ilgilenir.

2. Durumsuzluk (Statelessness)

Her API isteği, işlenmesi için gerekli tüm bilgiyi kendi içinde taşır. Sunucu, önceki isteklerden herhangi bir durum bilgisi saklamaz.

3. Önbelleklenebilirlik (Cacheability)

API yanıtları, önbelleğe alınabilir olarak işaretlenebilir. Bu, performansı artırır ve sunucu yükünü azaltır.

4. Katmanlı Sistem

İstemci, doğrudan sunucuyla mı yoksa bir ara katmanla mı iletişim kurduğunu bilmek zorunda değildir.

5. Tekdüze Arayüz

API'nin tutarlı ve öngörülebilir bir arayüz sunması, kullanılabilirliği artırır.

HTTP Metotları

RESTful API'lerde kaynak üzerinde yapılacak işlem HTTP metodu ile belirtilir:

HTTP Durum Kodları

API yanıtlarında işlemin sonucunu bildiren durum kodları kullanılır:

• 200 OK: İstek başarılı
• 201 Created: Yeni kayıt oluşturuldu
• 204 No Content: Başarılı, içerik yok (silme işlemleri)
• 400 Bad Request: Hatalı istek
• 401 Unauthorized: Yetkilendirme gerekli
• 403 Forbidden: Erişim reddedildi
• 404 Not Found: Kaynak bulunamadı
• 500 Internal Server Error: Sunucu hatası

İyi RESTful API Tasarımı İlkeleri

Kaynak Adlandırma

URL'lerde isim kullanın, fiil kullanmayın. Çoğul isimler tercih edin:

• Doğru: /api/products, /api/users/1/orders
• Yanlış: /api/getProducts, /api/deleteUser

Versiyonlama

API değişikliklerinde geriye uyumluluğu korumak için versiyonlama kullanın: /api/v1/products veya /api/v2/products

Filtreleme, Sıralama ve Sayfalama

Büyük veri setlerinde sorgu parametreleriyle filtreleme, sıralama ve sayfalama destekleyin:

• Filtreleme: /api/products?category=electronics&minPrice=100
• Sıralama: /api/products?sort=price&order=desc
• Sayfalama: /api/products?page=2&limit=20

Hata Yönetimi

Tutarlı ve bilgilendirici hata yanıtları döndürün. Hata mesajları, geliştiricinin sorunu anlamasına yardımcı olmalıdır.

API Güvenliği

API güvenliği kritik öneme sahiptir:

1. HTTPS kullanın: Tüm API trafiğini şifreleyin
2. Kimlik doğrulama: JWT, OAuth 2.0 veya API key kullanın
3. Rate limiting: İstek sayısını sınırlayarak kötüye kullanımı önleyin
4. Giriş doğrulama: Tüm gelen verileri doğrulayın ve temizleyin
5. CORS politikası: Hangi kaynakların API'ye erişebileceğini belirleyin

API Dokümantasyonu

İyi bir API, iyi bir dokümantasyonla birlikte gelir. Swagger (OpenAPI) ve Postman en yaygın dokümantasyon araçlarıdır. Dokümantasyonunuzda şunlar bulunmalıdır:

• Endpoint listesi ve açıklamaları
• İstek ve yanıt örnekleri
• Kimlik doğrulama bilgileri
• Hata kodları ve açıklamaları
• Rate limit bilgileri

REST Alternatifleri

Ekolsoft olarak RESTful API tasarımı ve geliştirme konusunda uzmanlaşmış ekibimizle, ölçeklenebilir ve güvenli API çözümleri sunuyoruz.

Sonuç

RESTful API tasarımı, modern yazılım geliştirmenin temel becerilerinden biridir. Bu rehberdeki ilkeleri uygulayarak temiz, tutarlı ve ölçeklenebilir API'ler geliştirebilirsiniz. İyi tasarlanmış bir API, hem geliştirici deneyimini hem de uygulamanızın başarısını doğrudan etkiler.