API (API (Uygulama Programlama Arayüzü))

#api #rest #graphql #yazilim-gelistirme

Farklı yazılım sistemlerinin standart kurallarla birbirleriyle iletişim kurmasını sağlayan arayüz.

API (Application Programming Interface — Uygulama Programlama Arayüzü), farklı yazılım sistemlerinin birbirleriyle standart kurallar çerçevesinde iletişim kurmasını sağlayan arayüzdür. Bir restoranın menüsü ve garson metaforu sıkça kullanılır: müşteri (istemci) menüden istediğini seçer, garson (API) siparişi mutfağa (sunucu/servis) iletir ve hazır yemeği geri getirir. Müşterinin mutfak detaylarını bilmesine gerek yoktur. Yapay zeka ekosisteminde API kullanımı merkezi bir rol üstlenir. OpenAI, Anthropic, Google ve Mistral gibi şirketler modellerini doğrudan REST API üzerinden sunar. Bir geliştirici ChatGPT'yi kendi uygulamasına entegre etmek istediğinde OpenAI API'ını çağırır; modelin mimarisini veya ağırlıklarını bilmesine gerek kalmaz. Bu yaklaşım, küçük startup'ların bile dünya genelindeki en güçlü modellere erişmesine olanak tanır. Günümüzde iki temel API mimarisi öne çıkar. REST (Representational State Transfer), HTTP protokolü üzerine inşa edilmiş, JSON formatında veri alışverişi yapan ve GET/POST/PUT/PATCH/DELETE metodlarını kullanan en yaygın yaklaşımdır. Durumsuz (stateless) yapısı ölçeklenebilirliği artırır. GraphQL ise Facebook tarafından 2015'te geliştirilen ve istemcinin tam olarak ihtiyaç duyduğu alanları sorgulayabildiği daha esnek bir dil sunar; fazla veya eksik veri çekme sorunlarını ortadan kaldırır. API güvenliği birkaç katmanda ele alınır. API anahtarı (API key) en basit yöntemdir; her istekte Authorization başlığında Bearer token olarak iletilir. OAuth 2.0, üçüncü taraf uygulamaların kullanıcı adına işlem yapmasına olanak tanıyan endüstri standardı yetkilendirme protokolüdür. JWT (JSON Web Token), içinde kullanıcı bilgisi barındıran imzalı token formatıdır. Rate limiting ise belirli süre içindeki istek sayısını sınırlayarak kötüye kullanımı engeller ve 429 Too Many Requests hata kodu döndürür. Türkiye'de e-ticaret platformları, ödeme sistemleri (İyzico, Stripe), harita servisleri ve bankacılık altyapıları API ekosistemi üzerine kurulu çalışır. Trendyol Seller API, satıcıların envanterini ve siparişlerini yazılımsal olarak yönetmesini sağlar. OpenAPI/Swagger standardı REST API'larını tanımlamak için kullanılan JSON Schema tabanlı spesifikasyon formatıdır; Swagger UI ile otomatik dokümantasyon ve etkileşimli test arayüzü oluşturulabilir.

API Nasıl Çalışır?

API, istemci ile sunucu arasında köprü görevi görür. Temel akış: (1) İstemci (uygulamanız) belirli bir endpoint'e HTTP isteği gönderir — örneğin GET /v1/models. (2) API sunucusu isteği doğrular ve iş mantığını çalıştırır. (3) Sunucu standart formatta (JSON/XML) yanıt döner. Bu yapı sayesinde farklı platformlardaki (iOS, Android, web) uygulamalar aynı backend ile çalışabilir. Bir API endpoint'i genellikle temel URL + kaynak yolu + sorgu parametrelerinden oluşur: `https://api.openai.com/v1/chat/completions?model=gpt-4o`.

Başlıca API Mimarileri

🔄 REST API

HTTP protokolü + JSON. GET (okuma), POST (oluşturma), PUT/PATCH (güncelleme), DELETE. Durumsuz yapısı ölçeklenebilirliği artırır. Web'deki en yaygın standart; OpenAI ve Anthropic bu mimariye dayanır.

📊 GraphQL

Facebook (2015). İstemci tam olarak ihtiyaç duyduğu alanları sorguya yazar; fazla veya eksik veri çekilmez. GitHub ve Shopify API'ları GraphQL kullanır. Tek endpoint, esnek şema.

⚡ gRPC / WebSocket

gRPC: Google'ın Protobuf tabanlı yüksek performanslı RPC çerçevesi; ML model serving'de yaygın. WebSocket: gerçek zamanlı çift yönlü bağlantı; canlı sohbet ve streaming yanıtlar için kullanılır.

API Güvenliği: Temel Mekanizmalar

  • check_circle API Anahtarı (API Key): En basit yöntem. Her istekte Authorization: Bearer sk-... başlığında gönderilir. Anahtar sızdırılırsa tüm erişim tehlikeye girer; ortam değişkenine (.env) alınmalı, asla koda gömülmemeli.
  • check_circle OAuth 2.0: Üçüncü taraf uygulamaların kullanıcı adına işlem yapmasını sağlayan endüstri standardı. 'Google ile giriş' düğmesi OAuth 2.0 kullanır. Erişim token'ı (access token) kısa ömürlü; yenileme token'ı (refresh token) uzun ömürlüdür.
  • check_circle Rate Limiting ve Throttling: Belirli sürede maksimum istek sayısı kısıtı. Aşıldığında 429 Too Many Requests döner. Retry-After başlığı bekleme süresini belirtir. Üretim sistemlerinde üstel geri çekilme (exponential backoff) ile yeniden deneme zorunludur.
  • check_circle JWT (JSON Web Token): Header.Payload.Signature formatında imzalı token. Sunucu durumsuzdur: token içindeki bilgi doğrulanır, veritabanına sorgu atılmaz. Stateless authentication için ideal; HS256 veya RS256 imza algoritması kullanılır.

Yapay Zeka API'larının Önemi

2023 sonrasında AI API ekosistemi patlama yaşadı. OpenAI `/v1/chat/completions`, Anthropic `/v1/messages`, Google Generative AI ve Mistral API, geliştiricilerin milyarlarca parametreli modelleri kendi altyapılarını kurmadan kullanmasına olanak tanır. Maliyet genellikle token başına hesaplanır (input + output). Anthropic Claude API'ında prompt caching özelliği sık kullanılan bağlamı önbelleğe alarak maliyeti %90'a kadar düşürür. LangChain ve LlamaIndex gibi çerçeveler birden fazla AI API'ını soyutlayarak kolayca değiştirilebilir hale getirir.

OpenAPI/Swagger ve Dokümantasyon Standartları

OpenAPI Specification (OAS), REST API'larını makine tarafından okunabilir JSON/YAML formatında tanımlar. Swagger UI bu spesifikasyondan otomatik interaktif dokümantasyon oluşturur; tarayıcı üzerinden endpoint'leri test etmek mümkün olur. Redoc ise daha şık bir alternatif sunar. Türkiye'deki kurumsal yazılım projelerinde Open Banking API'larından kamu e-devlet servislerine kadar OpenAPI standardı giderek zorunlu hale gelmektedir.

Sık Sorulan Sorular

  • check_circle API ile SDK arasındaki fark nedir?: API, ham HTTP endpoint'leri sunar; doğrudan curl veya herhangi bir HTTP istemcisiyle çağrılabilir. SDK (Software Development Kit) ise belirli bir programlama dili için API'ı sarmalayan hazır kütüphanedir. Örneğin OpenAI'nin Python SDK'si `openai.chat.completions.create()` çağrısını HTTP isteğine dönüştürür.
  • check_circle REST mi, GraphQL mi kullanmalıyım?: Kaynak tabanlı, basit CRUD operasyonları için REST; karmaşık, ilişkisel veri gereksinimleri ve istemci tarafında esnek sorgular için GraphQL tercih edilir. AI API'ları neredeyse tamamı REST kullanır; frontend ekip yoksa REST ile başlamak daha kolaydır.
  • check_circle API key'i nasıl güvende tutarım?: Asla kaynak koduna (GitHub'a) gömme. `.env` dosyasına yaz, `.gitignore`'a ekle. Sunucu ortamında environment variable olarak tüket. Sızdırılmışsa ilgili platformda hemen yenile. Backend'de proxy pattern kullanarak frontend'den gizle.
  • check_circle 429 Too Many Requests hatasıyla nasıl başa çıkılır?: Üstel geri çekilme (exponential backoff) uygula: ilk hata sonrası 1s, sonra 2s, 4s, 8s bekle. Retry-After başlığını kontrol et. Üretim sisteminde kuyruklama (queue) ile eşzamanlı istek sayısını sınırla. Token bucket veya leaky bucket algoritması ile rate limit yönetimi yapılabilir.
  • check_circle Streaming API nasıl çalışır?: OpenAI ve Anthropic gibi AI API'ları `stream=true` parametresiyle Server-Sent Events (SSE) akışı döner. Model yanıtı bitirmeden token token istemciye gönderilir; bu sayede kullanıcı ilk tokeni saniyeler içinde görür. Python'da `for chunk in client.messages.stream(...)` ile tüketilir.