API, iki yazılımın birbiriyle nasıl konuşacağını tarif eden bir arayüz. Açılımı Application Programming Interface, Türkçesiyle uygulama programlama arayüzü. API nedir sorusunun en kısa cevabı: bir programın başka bir programdan bir şey isteyebilmesi için açılmış bir kapı ve o kapının kuralları.

2020'den beri profesyonel olarak backend servisleri ve API'ler yazıyorum. Bu yazıda API'yi teknik bilgisi olmayan birine anlatır gibi başlayıp curl ile gerçek bir isteğe, oradan REST API'nin kurallarına, HTTP durum kodlarına ve kimlik doğrulamaya kadar gidiyorum.

API nedir? Basit bir anlatım

Bir restorandaki menüyü düşünün. Menü size neleri sipariş edebileceğinizi, her birinin ne içerdiğini ve nasıl isteyeceğinizi söylüyor. Mutfağın içinde ne olduğunu, hangi ocakta pişirildiğini bilmeniz gerekmiyor. Siparişi veriyorsunuz, yemek geliyor.

API de yazılımlar için bu menü. Bir hava durumu servisi "bana şehir adını gönder, sana sıcaklığı JSON olarak döneyim" diyor. Siz o servisin veritabanını, sunucularını, hangi dilde yazıldığını bilmeden yalnızca bu kurala uyarak veri alıyorsunuz.

Her gün kullandığınız uygulamalar API'lerle dolu:

  • Telefonunuzdaki bir uygulama, ekranda gördüğünüz veriyi kendi backend'inin API'sinden çekiyor.
  • Bir e-ticaret sitesi ödemeyi, bir ödeme sağlayıcısının API'si üzerinden alıyor.
  • "Google ile giriş yap" butonu Google'ın kimlik doğrulama API'sini kullanıyor.
  • Kargo takip sayfası, kargo firmasının API'sinden paketin nerede olduğunu soruyor.

Frontend ile backend arasındaki bağlantı da bir API. Bu ayrımı Backend nedir yazısında daha detaylı anlattım.

API ne işe yarar?

API'nin asıl değeri, sistemleri birbirinden ayırması. Mobil uygulama ile web sitesi aynı API'yi kullanıyorsa, iş kurallarını iki kez yazmıyorsunuz. Backend'i baştan yazsanız bile API aynı kaldığı sürece mobil uygulamaya dokunmanız gerekmiyor. Başka bir şirketin ödeme ya da harita servisini kendi ürününüze eklemek için de o servisin iç yapısını öğrenmeniz gerekmiyor, API dokümanı yetiyor.

"API" kelimesi bazen bir kütüphanenin fonksiyonları için de kullanılıyor. Örneğin bir Node.js paketinin dışarıya açtığı fonksiyonlar da onun API'si. Ama bugün "API" denince çoğu zaman kastedilen, HTTP üzerinden konuşulan web API'leri. Bu yazı da onlarla ilgili.

Gerçek bir API isteği: curl ile GitHub API

GitHub'ın herkese açık bir API'si var, onunla gerçek bir istek atalım. Terminalde:

curl https://api.github.com/users/halitsever

Cevap JSON olarak geliyor. Kısaltılmış hali:

{
  "login": "halitsever",
  "html_url": "https://github.com/halitsever",
  "name": "Halit Sever",
  "blog": "halit.org",
  "location": "Istanbul, Turkey",
  "public_repos": 45,
  "created_at": "2017-12-23T11:51:32Z"
}

Tarayıcıda gördüğünüz GitHub profil sayfasındaki bilgiler, ama süslü bir sayfa yerine programın okuyabileceği bir formatta. Bir program bu JSON'u alıp istediği gibi kullanabilir: bir portföy sitesinde depo sayısını göstermek, bir botta profil özeti yazmak.

Cevabın başlıklarını görmek için -i ekleyin:

curl -i https://api.github.com/users/halitsever
HTTP/2 200
content-type: application/json; charset=utf-8
x-ratelimit-limit: 60
x-ratelimit-remaining: 59
...

Burada üç şey okuyabiliyoruz. 200 isteğin başarılı olduğunu söylüyor. content-type cevabın JSON olduğunu söylüyor. x-ratelimit-limit: 60 de GitHub'ın kimlik doğrulaması yapmayan istemcilere saatte 60 istek hakkı verdiğini gösteriyor.

Olmayan bir kullanıcıyı istersek:

curl -i https://api.github.com/users/bu-kullanici-yok-12345xyz
HTTP/2 404
content-type: application/json; charset=utf-8

{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest",
  "status": "404"
}

İyi tasarlanmış bir API, hata durumunda da düzgün bir durum kodu ve okunabilir bir mesaj döndürüyor.

Bir HTTP isteğinin parçaları

Her web API isteği aynı parçalardan oluşuyor:

  • Metod: Ne yapmak istediğiniz. GET okumak, POST oluşturmak için.
  • URL: Hangi kaynağa istek attığınız. https://api.github.com/users/halitsever.
  • Header'lar: İstekle ilgili ek bilgiler. Kimlik bilgisi, gönderdiğiniz verinin formatı, istediğiniz dil.
  • Body: Gönderdiğiniz veri. GET isteklerinde genelde yok, POST ve PUT isteklerinde JSON olarak gidiyor.

Cevap da benzer: bir durum kodu, header'lar ve bir body.

REST API nedir?

REST, web API'lerini tasarlamak için kullanılan bir mimari tarz. Bir kütüphane ya da protokol değil, bir dizi kural. Bugün karşınıza çıkan web API'lerinin çoğu REST tarzında.

REST'in temel fikri şu: API'niz kaynaklardan (resource) oluşuyor ve her kaynağın bir URL'i var. Kullanıcılar, siparişler, ürünler birer kaynak. Bu kaynaklar üzerinde ne yapacağınızı URL değil, HTTP metodu söylüyor.

Bir sipariş API'si için:

MetodURLNe yapar
GET/siparislerSiparişleri listeler
GET/siparisler/4242 numaralı siparişi getirir
POST/siparislerYeni sipariş oluşturur
PATCH/siparisler/42Siparişin bazı alanlarını günceller
PUT/siparisler/42Siparişi bütünüyle değiştirir
DELETE/siparisler/42Siparişi siler

Dikkat ederseniz URL'lerde /siparisOlustur ya da /siparisSil gibi fiiller yok. URL isim, fiil metod. Bu kural uyulduğunda bir REST API'yi dokümanına bakmadan bile kısmen tahmin edebiliyorsunuz.

Yeni bir sipariş oluşturan istek şöyle görünüyor (adres örnek):

curl -X POST https://api.ornek.com/siparisler \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"urunId": 7, "adet": 2}'

Başarılı olursa sunucu 201 Created ve oluşan siparişi döndürüyor:

{
  "id": 43,
  "urunId": 7,
  "adet": 2,
  "durum": "beklemede"
}

REST'in diğer önemli kuralı stateless olması. Her istek, sunucunun onu anlaması için gereken her şeyi kendisi taşıyor. Sunucu "bu kullanıcı az önce giriş yapmıştı" diye bir şey hatırlamıyor, kimlik bilgisi her istekte header'da geliyor. Bu sayede aynı API'yi birden fazla sunucuya dağıtmak kolaylaşıyor, herhangi bir sunucu herhangi bir isteğe cevap verebiliyor.

HTTP durum kodları ne anlama gelir?

Durum kodu, sunucunun isteğinize kısa cevabı. İlk rakam kategoriyi söylüyor: 2 ile başlayanlar başarılı, 4 ile başlayanlar istemcinin hatası, 5 ile başlayanlar sunucunun hatası.

En sık karşılaşacaklarınız:

KodAnlamıNe zaman
200 OKBaşarılıOkuma ve güncelleme istekleri
201 CreatedOluşturulduPOST ile yeni kayıt açıldığında
204 No ContentBaşarılı, gövde yokGenelde DELETE sonrası
400 Bad Requestİstek hatalıEksik alan, geçersiz JSON
401 UnauthorizedKimlik doğrulanmadıToken yok ya da geçersiz
403 ForbiddenYetki yokKim olduğunuz biliniyor ama bu işe izniniz yok
404 Not FoundBulunamadıOlmayan bir kaynak
409 ConflictÇakışmaAynı e-postayla ikinci kayıt
422 Unprocessable ContentDoğrulama hatasıFormat doğru, içerik geçersiz
429 Too Many RequestsÇok fazla istekRate limit aşıldı
500 Internal Server ErrorSunucu hatasıSunucu tarafında yakalanmamış bir hata
503 Service UnavailableServis kullanılamıyorBakım ya da aşırı yük

API yazarken her şeye 200 dönüp hatayı body'ye yazmak yaygın bir hata. İstemci durum koduna bakarak ne olduğunu anlayabilmeli. 401 ile 403 arasındaki fark da sık karışıyor: 401 "sen kimsin bilmiyorum", 403 "kim olduğunu biliyorum ama buna iznin yok" demek.

API'lerde kimlik doğrulama nasıl yapılır?

Herkese açık birkaç API dışında, API'ler kimin istek attığını bilmek istiyor. Yaygın yöntemler:

API anahtarı. Servis size uzun, rastgele bir anahtar veriyor, siz de her istekte bunu bir header'da gönderiyorsunuz. Sunucudan sunucuya konuşan entegrasyonlarda yaygın. Anahtarı frontend koduna ya da git deposuna koymamak gerekiyor, gören herkes sizin adınıza istek atabilir.

Bearer token. Kullanıcı giriş yaptığında sunucu bir token veriyor, istemci sonraki isteklerde onu Authorization header'ında gönderiyor:

curl -H "Authorization: Bearer <token>" https://api.github.com/user

Token geçersizse GitHub 401 döndürüyor. Bu token'lar çoğu zaman JWT formatında oluyor: içinde kullanıcının kimliği ve son kullanma tarihi olan, sunucunun imzaladığı bir metin. Sunucu imzayı kontrol ederek token'ın kendisi tarafından üretildiğini anlıyor.

OAuth. "Google ile giriş yap" ya da "GitHub ile bağlan" akışlarının arkasındaki standart. Kullanıcı şifresini sizin uygulamanıza vermiyor. Google'a giriş yapıyor, Google da uygulamanıza sınırlı yetkili bir token veriyor.

Hangisini kullanırsanız kullanın, API'yi HTTPS üzerinden sunun. Düz HTTP'de token ağdaki herkesin görebileceği şekilde gidiyor.

REST dışında hangi API türleri var?

REST tek seçenek değil:

  • GraphQL'de tek bir endpoint var ve istemci hangi alanları istediğini sorguda kendisi yazıyor. Farklı ekranların farklı verilere ihtiyaç duyduğu uygulamalarda işe yarıyor.
  • WebSocket sürekli açık kalan, iki yönlü bir bağlantı. Sunucunun istemciye kendiliğinden veri göndermesi gereken sohbet ve canlı bildirim gibi işler için kullanılıyor.
  • gRPC, veriyi ikili formatta taşıyan bir yöntem. Tarayıcıdan çok backend servislerinin birbiriyle konuşmasında tercih ediliyor.

Yeni bir projede genel bir web ya da mobil uygulamanın backend'i için REST ile başlamak çoğu zaman yeterli.

Kendi API'nizi yazmak

Bir API yazmak için bir backend dili ve bir framework yetiyor. Node.js ile Express ya da NestJS, Python ile FastAPI, C# ile ASP.NET bu iş için kullanılan yaygın seçenekler. Ben NestJS ve TypeScript kullanıyorum. Node.js nedir yazısında hiçbir paket kullanmadan JSON döndüren küçük bir API yazıyorum, aynı endpoint'in Express versiyonu da orada.

Küçük bir örnek: açık kaynak projelerimin README'lerindeki başlık görselleri bir API'den geliyor. https://halitsever-api.vercel.app/api/repo-title?title=Logmoji adresine istek attığınızda, title parametresindeki metinle bir SVG görsel dönüyor. API'nin cevabı her zaman JSON olmak zorunda değil, görsel, PDF ya da düz metin de olabiliyor.

API'nizi yazdıktan sonra bir yere deploy etmeniz gerekiyor. Bunun için Docker nedir yazısındaki Docker Compose örneği, bir API'yi veritabanıyla birlikte çalıştırmanın en basit yolu. Bir projeniz için API ya da backend yazacak birini arıyorsanız freelance çalıştığım işlere göz atabilirsiniz.

Sık sorulan sorular

API ile web servisi aynı şey mi?

Web servisi, ağ üzerinden erişilen bir API türü. Her web servisi bir API, ama her API bir web servisi değil. Bir kütüphanenin fonksiyonları da bir API ama ağ üzerinden çalışmıyor.

REST API ile RESTful API arasında fark var mı?

Pratikte aynı şeyi anlatıyorlar. RESTful, REST kurallarına uyan API demek. Günlük kullanımda ikisi birbirinin yerine kullanılıyor.

API kullanmak için programlama bilmek gerekir mi?

Basit istekler için hayır. curl, Postman ya da Insomnia gibi araçlarla bir API'ye istek atıp cevabını görebilirsiniz. Gelen veriyi bir uygulamada kullanmak için ise biraz kod yazmanız gerekiyor.

API ücretli mi?

API'ye göre değişiyor. GitHub'ın yukarıdaki gibi ücretsiz kullanılabilen API'leri var, ödeme, harita ya da yapay zekâ API'lerinin çoğu kullanım başına ücretlendiriliyor. Kullanmadan önce servisin fiyatlandırma ve limit sayfasına bakın.

JSON nedir, neden her API'de var?

JSON, veriyi metin olarak taşımak için kullanılan basit bir format. Hem insanların okuyabileceği kadar sade hem de hemen her programlama dilinde hazır okuma desteği var. Bu yüzden web API'lerinin çoğu JSON kullanıyor.