API Nedir? RESTful API Geliştirme Rehberi ve Örnekleri

API, iki farklı yazılımın birbiriyle konuşabilmesi için tanımlanmış kurallar bütünüdür. Bir hava durumu uygulaması sıcaklık verisini kendi sunucusunda üretmez; meteoroloji servisinin API'sine istek gönderir ve gelen veriyi ekranda gösterir. RESTful API, bu iletişimi HTTP protokolü üzerinden belirli mimari kurallara göre kuran en yaygın API türüdür. Bu rehberde REST mimarisini, HTTP yöntemlerini, durum kodlarını ve gerçek örneklerle bir API'nin nasıl test edileceğini anlatıyoruz.

API tam olarak ne yapar

API (Application Programming Interface), bir sistemin başka bir sisteme sunduğu işlev kümesidir. Twitter'ın API'si üzerinden bir tweet'i kod ile paylaşabilirsiniz; arka planda hangi veritabanının çalıştığını bilmenize gerek kalmaz. Bu soyutlama katmanı sayesinde geliştirici, sadece isteği doğru formatta göndermekle yükümlüdür.

Restoran örneği bu ilişkiyi iyi özetler: siz (istemci) garsona (API) sipariş verirsiniz, garson mutfağa (sunucu) gider, yemeği alıp size getirir. Mutfakta ne olduğunu bilmezsiniz, sadece menüdeki seçeneklerle sınırlısınızdır. Menünün ne kadar net yazıldığı, yani dokümantasyonun kalitesi, API tasarımının kalitesini de belirler.

Web API'leri günlük hayatta en sık karşılaşılan türdür. Bir sitedeki "Google ile giriş yap" butonu, arka planda Google'ın OAuth API'sini çağırır. Ödeme sayfasındaki kart formu genelde Stripe veya iyzico gibi bir sağlayıcının API'sine istek atar; sitenin kendisi kart bilgisini hiç görmez.

REST mimarisi hangi kurallara dayanır

REST (Representational State Transfer), 2000 yılında Roy Fielding'in doktora tezinde tanımlanmış bir mimari stildir. Katı bir protokol değildir; altı kısıtlamadan oluşan bir yaklaşımdır. Bunların en önemli ikisi kaynak odaklılık ve durumsuzluktur (statelessness). Her varlık bir kaynaktır ve URL ile adreslenir: /api/users/42 kullanıcı 42'yi, /api/orders/17/items ise 17 numaralı siparişin ürünlerini temsil eder.

Durumsuzluk kuralı, sunucunun istekler arasında hiçbir oturum bilgisi tutmaması demektir. Her istek, kimlik doğrulama bilgisi dahil, kendi başına yeterli olmalıdır. Bu sayede sunucu yatay olarak ölçeklenebilir; herhangi bir sunucu herhangi bir isteği karşılayabilir, çünkü hiçbir sunucunun önceki isteği hatırlaması gerekmez.

Kaynak isimlendirmesinde çoğul isim ve iç içe yapı standarttır. /api/getUser?id=42 gibi fiil içeren URL'ler REST'e aykırıdır; doğrusu /api/users/42 gibi isim tabanlı, eylemi HTTP yöntemiyle belirten bir yapıdır. Bu ayrım sayesinde API'yi okuyan başka bir geliştirici, dokümantasyona bakmadan URL'den ne olduğunu tahmin edebilir.

HTTP yöntemleri CRUD işlemlerini nasıl karşılar

REST API'lerde her HTTP yöntemi, veritabanındaki bir CRUD işlemine karşılık gelir. GET veri okur, POST yeni kayıt oluşturur, PUT ve PATCH günceller, DELETE siler. Yöntem seçimi rastgele değildir; her yöntemin "güvenli" (safe) ve "idempotent" olup olmadığı REST'in temel varsayımlarından biridir.

İdempotent olmak, aynı isteği art arda beş kez göndermenin sonucunun, isteği bir kez göndermekle aynı olması demektir. PUT ile bir kullanıcının adını "Ahmet" yapmak beş kez tekrarlansa da sonuç değişmez. POST ile beş kez "yeni sipariş oluştur" isteği gönderirseniz beş ayrı sipariş oluşur. Bu fark, ağ hatası sonrası isteği yeniden denerken kritik hale gelir.

Gerçek bir kullanıcı oluşturma isteği şöyle görünür:

curl -X POST https://api.ornek.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{"name": "Ahmet Yılmaz", "email": "[email protected]"}'

Aynı kullanıcının yalnızca e-posta adresini güncellemek için PATCH kullanılır, PUT değil:

curl -X PATCH https://api.ornek.com/api/users/42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{"email": "[email protected]"}'

API yanıtları hangi bilgiyi taşır

Bir HTTP yanıtı üç parçadan oluşur: durum kodu, başlıklar (headers) ve gövde (body). Durum kodu isteğin sonucunu tek rakamla anlatır; 2xx başarıyı, 4xx istemci hatasını, 5xx sunucu hatasını gösterir. Gövde genelde JSON formatındadır, çünkü hem insan hem makine tarafından kolay okunur.

Başarılı bir POST isteğinin yanıtı genelde şöyle döner:

{
  "status": 201,
  "data": {
    "id": 42,
    "name": "Ahmet Yılmaz",
    "email": "[email protected]",
    "created_at": "2026-07-02T09:14:00Z"
  }
}

Hatalı bir istekte gövde, hatanın nedenini açıkça belirtmelidir; sadece "hata oluştu" yazan bir yanıt geliştiriciyi çaresiz bırakır. İyi tasarlanmış bir API şu formatı tercih eder:

{
  "status": 400,
  "error": "validation_error",
  "message": "email alanı gereklidir",
  "field": "email"
}

Kimlik doğrulama ve yetkilendirme nasıl ayrılır

Kimlik doğrulama (authentication) "sen kimsin" sorusuna, yetkilendirme (authorization) ise "neyi yapmaya iznin var" sorusuna cevap verir. Bir kullanıcının token'ı geçerli olabilir, ama başka bir kullanıcının siparişini silme yetkisi olmayabilir. Bu iki kavramı karıştırmak güvenlik açığının en sık nedenlerinden biridir. Modern API'lerin büyük bölümü Bearer token tabanlı JWT (JSON Web Token) veya OAuth 2.0 kullanır.

Her istekte token, Authorization başlığıyla taşınır:

GET /api/orders/17 HTTP/1.1
Host: api.ornek.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Rate limiting, bir istemcinin belirli sürede kaç istek atabileceğini sınırlar ve API'yi kötüye kullanıma karşı korur. Yanıt başlıklarında X-RateLimit-Remaining gibi alanlarla kalan hak bilgisi paylaşılır; limit aşıldığında 429 Too Many Requests döner. Girdi doğrulama (input validation) ise her isteği, veritabanına ulaşmadan önce tip ve uzunluk kontrolünden geçirir. Bu adım atlanırsa SQL enjeksiyonu gibi saldırılara kapı açılır.

• Kimlik bilgilerini asla URL parametresinde taşımayın, tarayıcı geçmişinde ve log dosyalarında kalır.
• Trafiği her zaman HTTPS üzerinden şifreleyin, düz metin HTTP'de token açıkta gider.
• Token'lara kısa ömür (örneğin bir saat) verip yenileme (refresh token) mekanizması kurun.
• Hassas alanları (şifre, kart numarası) yanıt gövdesinden asla geri döndürmeyin.

API çeşitleri ve mikroservis mimarisindeki rolü

Web API'leri dışında üçüncü taraf (third-party) API'ler de yaygındır: Google Maps, hava durumu servisleri ve ödeme sağlayıcıları gibi dış hizmetleri kendi uygulamanıza entegre etmenizi sağlarlar. Bunların çoğu kullanım başına ücretlendirilir ve genelde günlük veya aylık istek kotası uygular. Kotayı aşan istekler, yukarıdaki 429 durum koduyla reddedilir.

Mikroservis mimarisinde API'lerin rolü daha da belirginleşir. Büyük bir uygulama tek bir kod tabanı yerine küçük, bağımsız servislere bölünür; sipariş servisi, ödeme servisi ve stok servisi birbirleriyle sadece API üzerinden konuşur. Bu yapı, bir servisi güncellerken diğerlerini bozmadan dağıtım yapmayı mümkün kılar. Ancak servisler arası ağ trafiğini de artırır.

REST dışında GraphQL ve gRPC gibi alternatifler de vardır. GraphQL, istemcinin tam olarak ihtiyacı olan alanı seçmesine izin verir; gRPC ise yüksek performanslı iç servis iletişiminde tercih edilir. Bir projeye başlarken, özellikle dış geliştiricilere açık bir API sunuyorsanız, REST hâlâ en düşük öğrenme eğrisine sahip seçenektir.

API dokümantasyonu ve test araçlarıyla nasıl çalışılır

İyi bir API dokümantasyonu, her uç nokta (endpoint) için yöntem, parametreler, örnek istek ve örnek yanıtı birlikte gösterir. OpenAPI (eski adıyla Swagger) formatı bu dokümantasyonu makine tarafından da okunabilir hale getirir; birçok araç bu dosyadan otomatik test istemcisi üretir. Dokümantasyonu eksik bir API, teknik olarak çalışsa bile pratikte kullanılamaz.

Bir API'yi geliştirmeden önce test etmek için Postman veya Insomnia gibi araçlar kullanılır; bu araçlar istek geçmişini saklar ve ortam değişkenleri (environment variables) tanımlamanıza izin verir. Terminalden hızlı test için curl yeterlidir, ama karmaşık koleksiyonlarda görsel bir araç zaman kazandırır. HTTP yöntemleri hakkında ayrıntılı referans için MDN'in HTTP metotları sayfası ve durum kodları için MDN'in HTTP durum kodları sayfası güvenilir kaynaklardır.

Yeni bir API'ye başlarken önce sadece GET istekleriyle veri okumayı deneyin, kimlik doğrulama ve yazma işlemlerine daha sonra geçin. Böylece kaynak yapısını ve yanıt formatını bozmadan önce anlamış olursunuz. İlk POST isteğinizi göndermeden önce dokümantasyondaki her zorunlu alanı tek tek kontrol etmek, 400 hatalarıyla boğuşmaktan çok daha hızlıdır.

Bir API tasarlarken en çok zaman kazandıran alışkanlık, her hata yanıtına makine tarafından okunabilir bir error kodu ve insan tarafından okunabilir bir message alanı eklemektir. Bu tek adım, entegre eden geliştiricinin sizinle destek biletine gerek kalmadan sorunu kendi başına çözmesini sağlar.

Yazan Celil Uyanikoglu

25 yıldır bilgi işlem piyasasında farklı dallarda uzmanlaşan bir Bilgisayar Mühendisi