Web Servis (API)

Web servis (API — Application Programming Interface), farklı yazılım bileşenlerinin birbirleriyle güvenli ve standart bir şekilde konuşmasını sağlayan programlama arayüzüdür. Modern e-ticaret, mobil ve kurumsal uygulamalarda veri paylaşımı, entegrasyon ve otomasyonun temel taşıdır. Aşağıda hem iş hem de teknik ekiplerin ihtiyaç duyacağı tüm başlıkları kapsayan, uygulanabilir ve açık bir açıklama bulacaksınız.

Web Api Nedir?

Web servis (API), uygulamanızın belirli işlevlerini ve verilerini başka uygulamalara sunan tanımlı uç nokta (endpoint) koleksiyonudur. İstemciler (frontend, mobil, üçüncü parti sistemler) bu uç noktalara istek gönderir; API ise doğrular, işler ve yanıt döner.

Temel Türler

• REST (Representational State Transfer): En yaygın kullanılan; HTTP metodları (GET, POST, PUT, DELETE) üzerinden kaynak odaklı çalışır. JSON yaygın yanıt formatıdır.

• SOAP (Simple Object Access Protocol): XML tabanlı, katı sözleşmeli, kurumsal ve güvenlik gereksinimi yüksek entegrasyonlarda tercih edilir.

• GraphQL: İstemciye tam olarak ihtiyaç duyduğu veriyi sorgulama imkânı verir; overfetch/underfetch sorunlarını çözer.

• gRPC / Protobuf: Düşük gecikme ve yüksek performans gereken mikroservis iletişimlerinde kullanılır; ikili (binary) formatta çalışır.

Temel Bileşenler

• Uç Noktalar (Endpoints): Kaynakları temsil eden URL’ler.

• Metodlar: GET, POST, PUT, PATCH, DELETE vb.

• Sözleşme / Dokümantasyon: OpenAPI (Swagger), RAML veya WSDL (SOAP) gibi tanımlar.

• Veri Formatları: JSON, XML, Protobuf.

• Kimlik Doğrulama ve Yetkilendirme: OAuth2, JWT, API Key, mTLS.

• Hata Yönetimi: HTTP durum kodları + yapılandırılmış hata gövdesi.

• Rate Limiting & Throttling: İstemci taleplerini kontrol altına almak için.

• Versioning (Sürümleme): /v1/, header-based veya accept-version yaklaşımları.

Güvenlik (Mutlaka Uygulanmalı)

• TLS (HTTPS) zorunlu olsun.

• Yetkilendirme: OAuth2 veya JWT ile rol/tabanlı erişim kontrolü.

• Input validasyonu ve sanitizasyon — injection saldırılarına karşı.

• Rate limit & IP whitelisting ile brute-force/DoS koruması.

• Sensitive veri tokenizasyonu / şifreleme; PCI/KVKK/GDPR gereksinimlerine uygun saklama.

• Webhook güvenliği: HMAC signature doğrulaması.

Tasarım ve En İyi Uygulamalar

• Kaynak odaklı, anlamlı URL’ler kullanın (ör. GET /orders/{id}).

• İdempotent işlemleri ayırın (GET, PUT idempotent; POST değil).

• Tutarlı ve anlaşılır hata yapıları döndürün: { "code": 4001, "message": "Invalid email", "details": {...} }.

• Sayfalama (pagination), filtreleme ve sıralama sağlayın.

• Sürümleme stratejisi belirleyin ve geriye dönük uyumluluğu koruyun.

• HATEOAS gerekliyse uygulanabilir, aksi halde basit REST tercih edin.

• Timeout ve retry mantıklarını istemci tarafında belirleyin.

• OpenAPI spec ile tam dokümantasyon ve otomatik test/SDK üretimi sağlayın.

Performans ve Ölçeklenebilirlik

• Cache: GET cevaplarını cache-lenebilir yapın (Cache-Control, ETag).

• Load balancing + autoscaling ile yatay ölçeklendirme.

• CDN ve edge caching kullanımı (statik içerik/görseller için).

• Asenkron işlemler için kuyruk (RabbitMQ, Kafka) ve webhook bildirimleri.

• Profiling ve APM (Application Performance Monitoring) ile gecikme takibi.

İzleme, Loglama ve Hata Yönetimi

• Merkezi loglama (ELK/EFK, Datadog).

• Sağlık kontrolleri (liveness/readiness endpoints).

• Metrix: latency, throughput, 4xx/5xx oranları, success rate.

• Alerting: SLA eşikleri için uyarı kuralları.

• Trace ID: Talepleri uçtan uca izleyecek correlation-id mekanizması.

Test ve Kalite Güvencesi

• Unit, integration ve contract (consumer-driven) testleri.

• API contract testleri: Pact veya OpenAPI bazlı testler.

• Load / stress testleri: JMeter, k6.

• Security testing: SAST ve DAST taramaları.

• Mock server ile frontend geliştirme paralelliği sağlayın.

Dokümantasyon & Geliştirici Deneyimi

• OpenAPI (Swagger) ile hem dokümantasyon hem otomatik SDK üretimi sağlayın.

• Postman collection ve örnek istek/yanıtlar sunun.

• Hızlı başlama (quickstart) rehberi: authentication token alma, örnek akış.

• SDK’lar (JavaScript, Python, PHP, Java) ve örnek uygulamalar.

• Change log ve migration rehberi ile sürüm güncellemelerini yönetin.

Entegrasyon Süreci (Adım Adım)

1. İhtiyaç analizi: Hangi veriler, hangi frekansta paylaşılacak?

2. API sözleşmesi taslağı: Uç noktalar, veri modelleri, hata kodları.

3. Prototip / Mock server oluşturma ve frontend ile eş zamanlı test.

4. Güvenlik ve kimlik doğrulama mekanizmalarının kurulması.

5. Test ortamında end-to-end testleri ve yük testleri.

6. Canlıya alma (canary/blue-green deployment önerilir).

7. İzleme, loglama ve mutabakat süreçlerinin aktif edilmesi.

8. SLA, destek ve değişiklik yönetimi süreçlerinin belirlenmesi.

Faydalar (İş Perspektifi)

• Hızlı entegrasyon: Üçüncü taraflarla hızlı veri paylaşımı.

• Otomasyon: Manual süreçleri azaltıp hata oranını düşürür.

• Yenilik hızı: Yeni kanalları (mobil, pazar yerleri, POS) çabucak bağlarsınız.

• Ölçeklenebilir iş modelleri: Mikroservis mimarileri ve B2B/partner entegrasyonları kolaylaşır.

• Ölçülebilirlik: Performans ve kullanım metrikleri ile iş kararları desteklenir.

Kimler İçin? (Hedef Kitle)

• E-ticaret siteleri ve pazar yerleri

• ERP / WMS / CRM sistemleri ile entegrasyon gereksinimi olan firmalar

• Mobil uygulama sahipleri

• SaaS sağlayıcıları ve B2B iş ortakları

• IoT çözümleri ve mikroservis mimarisi uygulayan ekipler

Uygulama Örneği (Kısa)

• POST /api/v1/orders → Sipariş oluşturur; body içinde ürün listesi, ödeme bilgisi token’ı, teslimat adresi.

• GET /api/v1/orders/{id} → Sipariş detayını döner; header’da X-Correlation-ID bekler.

• POST /api/v1/webhooks/payment → Ödeme durumu bildirimi; HMAC signature doğrulaması yapılır.

Hızlı Kontrol Listesi (Checklist)

• OpenAPI dökümantasyonu var mı?

• HTTPS + TLS 1.2/1.3 aktif mi?

• Authentication: OAuth2/JWT veya API Key?

• Rate limiting uygulandı mı?

• Hata formatı tutarlı mı?

• Sürümleme stratejisi belirlendi mi?

• Monitoring ve alerting kuruldu mu?

• Test (unit/integration/load/security) süreçleri tamam mı?

• API sürümünü nasıl yönetmeliyim? Minor değişiklikler geriye dönük uyumlu olmalı; breaking change’ler yeni sürümle verilmeli.

• Webhook güvenliğini nasıl sağlarım? HMAC signature + timestamp + replay koruması.

• Ne kadar rate limit koymalıyım? İş yükünüza ve SLA’ya göre; başlangıç için 100 req/min gibi kademeli limitler test edilebilir.

• Dokümantasyon için en iyi araç nedir? OpenAPI + Swagger UI + Postman koleksiyonu güçlü bir kombinasyondur.