İçeriğe atla
Bilgi Merkezi/Makale
Makale

API Nedir, Ne Demek? REST API, API Gateway ve Güvenliği

API'nin nasıl çalıştığını, HTTP metotlarını, REST ve OpenAPI'yi, GraphQL ile gRPC'yi, API gateway'i, kimlik doğrulamayı ve güvenliği anlattık.

Oğuzhan Gerçek··8 dk okuma
API Nedir, Ne Demek? REST API, API Gateway ve Güvenliği

Kısa cevap: API (Application Programming Interface, uygulama programlama arayüzü), bir yazılımın başka yazılımlara sunduğu ve hangi isteğe hangi cevabın döneceğini tanımlayan sözleşmedir. Web API'lerinde istemci HTTP ile GET ya da POST gibi bir istek gönderir, sunucu bir durum kodu ve veriyle cevap verir. REST bu API'lerin dayandığı mimari stillerden biri, OpenAPI ise bu sözleşmeyi yazmak için bir standart. API gateway yönlendirme, kimlik doğrulama ve istek sınırlama (rate limiting) işlerini üstlenir. OWASP'ın API güvenliği listesinde ilk sıradaki risk, kullanıcının istekteki nesne kimliğini (ID) değiştirerek başkasının verisine ulaşabilmesidir.

API nedir, ne demek?

API, Application Programming Interface'in kısaltması. NIST'in sözlüğüne göre uygulama programlarının erişebildiği, sözdizimi iyi tanımlanmış bir sistem erişim noktası ya da kütüphane işlevidir. AWS'nin anlatımıyla iki yazılım bileşeninin tanımlar ve protokollerle konuşmasını sağlar: isteği gönderen istemci, cevaplayan sunucudur. Örneğin bir mobil uygulama, veritabanına SQL sorgusuyla doğrudan bağlanmak yerine API'nin adresine istek gönderir; sözleşme korunduğu sürece sunucu tarafı değişse de uygulama çalışır. Terimin kısa tanımı sözlüğümüzde var.

Web API'leri: HTTP metotları ve durum kodları

Web API'leri HTTP üzerinde çalışır; HTTP'nin anlamını RFC 9110 (Haziran 2022, STD 97) tanımlar. Başlıca metotların MDN'deki tanımları ve IANA kaydındaki özellikleri şöyle:

  • GET: Kaynağın bir temsilini ister; güvenli (safe) ve idempotent.
  • POST: Kaynağa veri gönderir, çoğu zaman sunucuda durum değiştirir; ne güvenli ne idempotent.
  • PUT: Kaynağın tamamını gönderilen içerikle değiştirir; idempotent.
  • PATCH (RFC 5789): Kısmi değişiklik yapar; idempotent sayılmaz.
  • DELETE: Kaynağı siler; idempotent.

Güvenli metot sunucunun durumunu değiştirmez; idempotent bir isteği birkaç kez göndermek ise tek seferle aynı etkiyi yapar, bu yüzden istek güvenle tekrarlanabilir. Durum kodunun ilk rakamı IANA'ya göre sınıfı gösterir: 2xx başarı, 4xx istemci hatası, 5xx sunucu hatası. 401 geçerli kimlik bilgisi olmadığını, 403 kimlik geçerli olsa da yetki bulunmadığını söyler. Örnek bir istek ve cevap şöyle görünür:

GET /v1/musteriler/1042 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer <erisim-tokeni>

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1042, "unvan": "Örnek A.Ş.", "durum": "aktif"}

Bearer token kullanımını RFC 6750 tanımlıyor. İsteğin sunucuya yolculuğunu web sunucusu yazımızda, bağlantının şifrelenmesini SSL yazımızda anlattık.

REST API nedir?

REST (Representational State Transfer), Roy Fielding'in 2000'de University of California, Irvine'da tamamladığı doktora tezinde tanımladığı bir mimari stildir. Tezin 5. bölümüne göre kısıtları şunlar:

  • İstemci-sunucu: Arayüz ile veri saklama ayrılır.
  • Durumsuzluk (stateless): Her istek, anlaşılması için gereken bütün bilgiyi taşır.
  • Önbellek (cache): Cevap, önbelleğe alınıp alınamayacağını belirtir.
  • Tek tip arayüz (uniform interface): Kaynaklar tanımlanır ve temsiller üzerinden işlenir.
  • Katmanlı sistem: Bileşen yalnızca komşu katmanı görür; ara katmanlar yük dengeleyebilir.
  • Talep üzerine kod (code-on-demand): İstemci betik indirip çalıştırabilir; tezdeki tek isteğe bağlı kısıt.

AWS'ye göre RESTful API'ler HTTP tabanlıdır, durumsuz iletişim kurar ve standart HTTP metotlarını kullanır. Örnekteki cevapta JSON kullanılıyor. RFC 8259'a (Aralık 2017, STD 90) göre JSON hafif, metin tabanlı ve dilden bağımsız bir veri değişim biçimidir.

OpenAPI: API sözleşmesini yazmak

OpenAPI Spesifikasyonu (OAS), HTTP API'leri için dilden bağımsız, standart bir arayüz tanımlar; böylece insanlar da bilgisayarlar da servisin yeteneklerini kaynak koda bakmadan anlayabilir. Belge JSON ya da YAML olarak yazılabilir. Dokümantasyon ve kod üreten araçlar ile test araçları bu belgeyi kullanır; testler bir CI/CD pipeline'ında da çalışabilir. 3.2.0 sürümü 19 Eylül 2025'te, onun ilk yama sürümü 3.2.1 ise 10 Eylül 2026'da yayımlandı. Belirtim, SmartBear'in bağışladığı Swagger belirtimine dayanıyor.

GraphQL, gRPC ve webhook

REST tek seçenek değil:

  • GraphQL: Eylül 2025 tarihli güncel belirtimine göre veri modelleri için bir sorgu dili ve yürütme motoru. İstek cevabın biçiminde yazılır; cevap da istemcinin istediğini içerir, fazlasını değil.
  • gRPC: CNCF'in incubation aşamasındaki açık kaynak RPC (uzak yordam çağrısı) çerçevesi. İstemci, başka makinedeki bir metodu yerel bir nesneymiş gibi çağırır; mesaj biçimi için varsayılan olarak Protocol Buffers, taşıma için HTTP/2 kullanır.
  • Webhook: Olay gerçekleştiğinde sağlayıcı, önceden verilen adrese bir HTTP isteği gönderir. GitHub'a göre bu yöntem, API'yi düzenli sorgulamaktan (polling) daha az emek ve kaynak ister.

API gateway nedir?

API gateway, istemciler ile arka uçtaki (backend) servisler arasındaki giriş noktasıdır. Azure API Management belgesine göre bütün istekler önce gateway'e gelir; bu cephe (facade) sayesinde sağlayıcı arka ucu, API'yi kullananları etkilemeden değiştirebilir. Gateway'in işleri şunlar:

  • Çağrıyı doğru servise yönlendirmek
  • API anahtarını, JWT'yi ve sertifikaları doğrulamak
  • Kota ve istek sınırlarını uygulamak, cevapları önbelleğe almak
  • Log, metrik ve trace üretmek (log yazımız)

Mikroservis mimarisinde servisler iyi tanımlanmış API'lerle konuşur ve bağımsız olarak devreye alınır; istemci servisleri değil, gateway'i çağırır. Container tarafını Docker ve Kubernetes yazılarımızda anlattık; bu katmanın işletimini Application Runtime & Middleware Operasyonları hizmetimizde ele alıyoruz.

API'de kimlik doğrulama: API anahtarı, OAuth 2.0 ve JWT

  • API anahtarı: İstemciyi tanıtan gizli değer. OWASP'a göre hizmet engelleme saldırılarının etkisini azaltabilir, ama hassas kaynaklarda tek başına ona güvenilmemeli; anahtar adreste (URL) değil, başlıkta taşınmalı.
  • OAuth 2.0: RFC 6749'un (Ekim 2012) tanımladığı bu çerçevede uygulama, bir HTTP hizmetine kullanıcının parolasıyla değil, sınırlı bir erişim token'ıyla bağlanır. RFC 9700 (Ocak 2025, BCP 240) implicit grant'ın kullanılmamasını, parolanın doğrudan istemciye verildiği password grant'ın ise hiç kullanılmamasını istiyor.
  • JWT: RFC 7519'a (Mayıs 2015) göre beyanları (claim) kompakt biçimde taşıyan, imzalanabilen ya da şifrelenebilen token. OWASP imzasız ("alg":"none") token'ların reddedilmesini istiyor.

OAuth 2.0'ın üstündeki OpenID Connect'i ve en az yetki ilkesini IAM yazımızda anlattık.

API güvenliği: OWASP API Security Top 10 ve istek sınırlama

OWASP'ın 5 Haziran 2023'te yayımladığı API Security Top 10 2023 listesinin ilk beş maddesi şunlar:

  1. API1:2023 Broken Object Level Authorization: Saldırgan istekteki nesne kimliğini değiştirerek başkasının kaydına ulaşabilir; OWASP kayda erişen her işlevde yetki kontrolü istiyor.
  2. API2:2023 Broken Authentication: Hatalı kimlik doğrulama yüzünden token'ların ele geçirilmesi.
  3. API3:2023 Broken Object Property Level Authorization: Nesnenin alanları için yetki denetimi eksikliği.
  4. API4:2023 Unrestricted Resource Consumption: CPU, bellek, depolama ve bant genişliği tüketimine sınır konmaması.
  5. API5:2023 Broken Function Level Authorization: Yönetici ve sıradan işlevlerin net ayrılmamasından doğan yetki hataları.

Kalan maddeler SSRF, yanlış yapılandırma ve eksik API envanteri gibi riskleri kapsıyor. API4'e karşı OWASP istek sınırlama öneriyor; sınır aşılınca RFC 6585'in (Nisan 2012) tanımladığı 429 Too Many Requests döner, Retry-After başlığı da bekleme süresini bildirebilir. Yetkilendirme genellikle kodda uygulandığı için WAF, başkasına ait kaydın istenmesini sıradan bir istek sayabilir. Bu katmanı uygulama güvenliği (WAF) hizmetimizde ele alıyoruz.

Sürümleme, geriye uyumluluk ve entegrasyon

Google'ın AIP-180 kılavuzuna göre API'ler kullanıcılarla yapılmış sözleşmelerdir; minor ya da patch sürüm mevcut istemci kodunu bozmamalı. Yeni alan ya da metot eklemek uyumludur; bir bileşeni kaldırmak, yeniden adlandırmak, türünü ya da varsayılan değerini değiştirmek uyumluluğu bozar. AIP-185 ise major sürümü adreste (v1 gibi) taşıyor, minor ve patch numaralarını göstermiyor. Bir sürümün kullanımdan kaldırıldığını (deprecated) RFC 9745'in (Mart 2025) tanımladığı Deprecation başlığı bildirir; adresin hangi tarihten sonra cevap vermeyebileceğini RFC 8594'teki Sunset başlığı gösterir.

API'lerin SaaS uygulamalarını birbirine bağlamasını SaaS yazımızda, toplu veri aktarımını ETL yazımızda anlattık. Bir entegrasyonun yeniden deneme kurgusu, idempotent metotları ve Retry-After başlığını hesaba katmalı. Sistemler arası entegrasyonu sistem entegrasyonu hizmetimizde ele alıyoruz.

Sık sorulan sorular

API ne demek? Application Programming Interface, yani uygulama programlama arayüzü demek: bir yazılımın başka yazılımlara sunduğu istek ve cevap sözleşmesi.

REST API nedir? REST mimari stiline uyan, HTTP tabanlı API'dir. Kaynaklar adreslerle tanımlanır ve GET, POST, PUT ya da DELETE gibi metotlarla işlenir.

GraphQL nedir? API'ler için bir sorgu dili ve yürütme motorudur. İstemci istediği alanları sorguda belirtir, cevap yalnızca bunları içerir.

API gateway nedir? API'lerin önündeki giriş noktasıdır. İsteği doğru servise yönlendirir, kimlik bilgilerini doğrular ve istek sınırlarını uygular.

Kaynaklar