Ana içeriğe atla

​
Politika Kavramı

Politika, API Gateway’de istemciden gelen istekleri ve Backend API’den dönen yanıtları belirli kurallara göre işlemek için kullanılan yapılandırılabilir bir bileşendir. Politikalar konfigürasyon temelli çalışır ve kod yazmaya gerek yoktur. Politikalar aracılığıyla aşağıdaki işlemleri gerçekleştirebilirsiniz:
  • Güvenlik kuralları uygulayabilirsiniz. Kimlik doğrulama (Basic Auth, OAuth2, OIDC, JWT vb.) ve yetkilendirme (role-based access control) mekanizmalarını politikalar ile tanımlarız.
  • Trafik yönetimi yapabilirsiniz. Kullanıcılar veya uygulamalar başına düşen kota (belirli dönem içinde yapılabilecek istek sayısı) ve hız sınırı (rate limiting) politikaları ile API’lerinizi aşırı yüklenmelerden koruyabilirsiniz.
  • Veri dönüşümü sağlayabilirsiniz. Gelen istekleri veya dönen yanıtları farklı formatlara dönüştürebilirsiniz (örneğin XML’i JSON’a çevirme, veri yapısını yeniden biçimlendirme).
  • Hata mesajlarını özelleştirebilirsiniz. Sistem tarafından dönen hata mesajlarını, kurumsal standartlara veya kullanıcı dostu bir dile çevirebilirsiniz.
  • İş mantığı uygulayabilirsiniz. JavaScript veya Groovy gibi betik dilleri veya koşullu mantık politikaları kullanarak basit iş kurallarını API Gateway seviyesinde tanımlayabilirsiniz.
  • Mesaj içeriğini zenginleştirebilirsiniz. İstek veya yanıta header ekleyebilir, metadata ekleyebilir veya hassas verileri maskeyleyebilirsiniz.
Politikalar, bir API Proxy’de mesajların işlenmesi sırasında uygulanan işlemleri tanımlar. Her politika belirli bir işlevi yerine getirir ve mesaj akışı içinde belirli bir noktada çalıştırılır. Arayüzde sürükle-bırak, parametre girişi veya konfigürasyon seçimleriyle politikaları anında etkinleştirebilir, güncelleyebilir veya devre dışı bırakabilirsiniz.

Yapılandırılabilir

Politikalar form tabanlı arayüzlerle yapılandırılır. Kod yazmaya gerek yoktur.

Yeniden Kullanılabilir

Politikalar global olarak tanımlanabilir ve birden fazla API Proxy’de kullanılabilir.

Koşullu Çalıştırma

Politikalar koşullara bağlı olarak çalıştırılabilir.

Sıralı İşleme

Politikalar bir pipeline içinde sırayla çalıştırılır.

​
Politika Uygulama Akışı

Aşağıdaki diyagram, politikaların mesaj akışında nasıl uygulandığını high-level olarak gösterir:

​
Politikanın Amacı ve Faydaları

Merkezi Kontrol API’lerin davranışı, güvenliği ve performansı tek bir noktadan yönetilir. Bu sayede dağıtık sistemlerde tutarlılık sağlanır ve yönetim karmaşıklığı azalır. Erişim Denetimi (Access Control) Politikaları Kimlik doğrulama, yetkilendirme ve API kaynaklarına erişim izinleri politikalar aracılığıyla tanımlanır. Böylece yetkisiz erişimler önlenir ve güvenlik sağlanır. Yeniden Kullanılabilirlik Bir kez tanımlanan politika, birden fazla API, endpoint veya servis tarafından kullanılabilir. Bu, politika yönetimini basitleştirir ve geliştirme sürecini hızlandırır. Kod Bakım Yükünü Azaltma Güvenlik, veri dönüşümü ve doğrulama işlemleri kod içinde değil, gateway konfigürasyonunda yapılır. Bu, uygulamaların kodundaki karmaşıklığı azaltır ve bakım maliyetlerini düşürür. Tutarlılık Tüm API’ler aynı politikalara tabi olduğundan, enterprise-wide güvenlik ve performans standartları tutarlı şekilde uygulanır. İstisnalar minimal düzeyde kalır. Hızlı Müdahale ve Esneklik Politikalar anında devre dışı bırakılabilir, güncellenebilir veya yeniden deploy edilebilir. Böylece güvenlik tehditlerine hızlı yanıt verilir, performans sorunları çözülür veya iş kuralları değişikliğe uyum sağlanır.

​
Politika Türleri

​
Güvenlik Politikaları

Kimlik Doğrulama

  • OAuth2
  • OIDC
  • JWT
  • Basic Authentication
  • Digest Authentication
  • mTLS

Yetkilendirme

  • IP Whitelist/Blacklist
  • API Key
  • Role-based Access Control

​
Trafik Yönetimi Politikaları

Rate Limiting

  • API Bazlı Daraltma
  • API Bazlı Kota
  • Zaman Kısıtlaması

Load Balancing

  • Yük dengeleme stratejileri
  • Failover

​
Mesaj İşleme Politikaları

Doğrulama

  • JSON Schema Doğrulama
  • XML Schema Doğrulama
  • Min/Max Mesaj

Dönüştürme

  • JSON Dönüştürme (Jolt)
  • XML Dönüştürme (XSLT)
  • Plain Text

​
Mesaj Zenginleştirme ve İş Mantığı Politikaları

Zenginleştirme

  • Header ekleme
  • Veri ekleme
  • Script (Groovy/JavaScript)

İş Kuralı

  • Koşullu iş mantığı
  • Aksiyon zinciri
  • Veri manipülasyonu

API Çağrısı

  • Harici API çağrıları
  • Veri çekme
  • Entegrasyon

Güvenlik

  • Şifreleme/Şifre Açma
  • Dijital İmza
  • Redaction (Maskeleme)
Tüm politika türleri ve detaylı açıklamaları için Politikalar sayfasına bakabilirsiniz.

​
Politika Pipeline

Politikalar bir pipeline içinde sırayla çalıştırılır: 
Request Pipeline:
├─ Pre-flow Politikaları (İstek öncesi)
├─ Koşullu Politikalar
├─ Yönlendirme Adımı
├─ Post-flow Politikaları (İstek sonrası)
└─ Response Pipeline:
   └─ Post-flow Politikaları (Yanıt sonrası)
   └─ Fault Handler Politikaları (Hata durumunda)

​
Pipeline Aşamaları

İstek backend’e gönderilmeden önce çalışan politikalar:
  • Kimlik doğrulama
  • Yetkilendirme
  • Rate limiting
  • Mesaj doğrulama
Koşullara bağlı olarak çalışan politikalar:
  • IF-THEN-ELSE mantığı
  • Mesaj içeriğine göre çalıştırma
  • Header değerlerine göre çalıştırma
İsteğin backend’e yönlendirildiği adım:
  • Upstream target seçimi
  • Load balancing
  • Failover
Backend’den yanıt geldikten sonra çalışan politikalar:
  • Yanıt dönüştürme
  • Maskeleme
  • Loglama
  • Header ekleme
Hata durumlarında çalışan politikalar:
  • Hata yakalama (Connection Error, Timeout Error, 4xx/5xx Errors)
  • Hata sınıflandırma
  • Hata mesajı dönüştürme
  • Hata loglama
  • Özelleştirilmiş hata yanıtı

​
Politika Kullanım Tipleri

​
Yerel Politika

Yalnızca oluşturulduğu API Proxy’de veya API Proxy Grupta geçerlidir. Bulunduğu API Proxy veya API Proxy Grup silinirse politika da silinir. Bulunduğu yerde export, import, activate, deactivate işlemleri yapılabilir.

​
Global Politika

Global Politikalar sayfasında oluşturulan politikalardır. Birden fazla API Proxy veya API Proxy Grup tarafından kullanılabilir. Global politikada değişiklik yapılırsa, politikayı kullanan tüm API Proxy’ler ve API Proxy Gruplar “Redeploy Required” durumuna geçer. Bu ekrandaki toplu deploy işlemi ile ilgili tüm API Proxy/API Proxy Gruplar birlikte deploy edilebilir. Ayrıca bu ekranlardan politika export, import, activate, deactivate işlemleri de gerçekleştirilebilir. Global Politikayı Yerelleştirme: Global olarak oluşturulmuş politika bir API Proxy/API proxy Group’da kullanımı sırasında özelleştirilmesi gerekebilir. Bu durumda API Proxy/API proxy Group’a eklenen politikaya tıklanır ve sağ üst köşedeki “Yerelleştir” tuşuna basılarak tek tıklama ile yerel hâle getirilebilir. Global Politikanın Kullanıldığı Yerler: Bir global politikanın hangi API proxylerde, API proxy gruplarında veya politika gruplarında kullanıldığını takip etmek, yönetim ve güncelleme süreçlerinde kritik öneme sahiptir. Her politika detay sayfasında, politikanın kullanım bilgileri görüntülenir:
  • Kullanıldığı API Proxy’ler Paneli: Bu bölümde, politikayı kullanan API Proxy’lerin listesi görüntülenir.
  • Kullanıldığı API Proxy Grupları Paneli: Bu bölümde, politikayı kullanan API Proxy gruplarının listesi görüntülenir.
  • Kullanıldığı Politika Grupları Paneli: Bu bölümde, bu politikayı içeren politika gruplarının listesi görüntülenir.

​
Global ve Yerel Politika Karşılaştırması

Global PolitikaLocal Politika
Birden fazla API Proxy’de kullanılabilirSadece bir API Proxy’de kullanılır
Merkezi yönetilirProxy bazında yönetilir
Bir kez güncellenir, tüm kullanımlar etkilenirHer proxy için ayrı güncelleme gerekir
Yeniden kullanılabilirliği yüksekYeniden kullanılabilirliği düşük

​
Politika Uygulama Noktaları

Politikalar üç farklı seviyede uygulanabilir:
Uygulama NoktasıAçıklama
API Proxy GrubuBir gruptaki tüm API Proxy’lere uygulanır
API ProxyBelirli bir API Proxy içindeki tüm metot/endpoint’lere uygulanır
Metot/EndpointYalnızca ilgili metot veya endpoint için geçerlidir
Politikaların mesaj akışındaki uygulama sırası, API Proxy Group/API Proxy/Endpoint seviyelerindeki çalışma mantığı ve görsel akış diyagramı hakkında detaylı bilgi için Mesaj İşleme ve Politika Uygulama sayfasına bakınız.

​
Politika Yapısı

Politikalar, fonksiyonel farklarına rağmen aynı temel yapıyı paylaşır.

​
Genel Bilgi Paneli

Her politikanın adı, açıklaması aktif olup olmadığı bilgileri ortak alanlarıdır. Ortak alanlar sonrasında politikaya özel konfigürasyon alanları yer alır.

​
Koşullar

Politikalar, yalnızca belirli koşullar sağlandığında çalışacak şekilde özelleştirilebilir. Örnek:
  • status parametresi "pending" ise çalış.
  • userId alanı #user1#user2#user3 listesindeyse işlet.
Bu özellik, politikaların dinamik ve bağlama duyarlı şekilde çalışmasını sağlar. Koşul değer kıyaslama operatörü olarak “listede olsun” veya “listede olmasın” seçeneği seçildiğinde, liste değerlerinin ayrımı için # işareti kullanılmalıdır. Örneğin user1#user2#user3 gibi.

​
Hata Mesajı Özelleştirme (Error Message Customization)

Politika çalışması sırasında oluşabilecek hatalar için dönen mesajlar özelleştirilebilir. Bu sayede geliştiriciler, istemcilere dönen hata mesajlarını kurumsal veya anlaşılır biçimde özelleştirebilir. Her politika, hata oluştuğunda dönecek mesajları özelleştirebilir:
AlanAçıklama
HTTP Status CodeVarsayılan sistem kodu
Error CodeVarsayılan hata kodu
Original MessageVarsayılan hata mesajı
Customized HTTP Status CodeFarklı bir HTTP durum kodu döndürülür
Customized Error CodeFarklı hata kodu belirlenir
Customized Error MessageÖzel hata mesajı yazılır
Not: Politika tanımlama arayüzünde o politika özelinde hata kodları ve mesajları özelleştirilebileceği gibi, platform genelinde de hata özelleştirme yapılabilir.

​
Politika Yapılandırması

Politikalar form tabanlı arayüzlerle yapılandırılır. Her politika türünün kendine özgü yapılandırma seçenekleri vardır.

​
Global Politikalar

Politikalar global olarak tanımlanabilir ve birden fazla API Proxy’de kullanılabilir. Bu sayede:
  • Politika tekrarı önlenir
  • Merkezi yönetim sağlanır
  • Tutarlılık korunur

​
Politika Grupları

Politika Grupları, ilgili politikaların gruplandırılarak birlikte yönetilmesini sağlar. Politika Grupları sayesinde:
  • Merkezi Yönetim: İlgili politikalar tek bir grup altında toplanır
  • Kolay Uygulama: Politika Grubu bir API Proxy’ye eklendiğinde, grubun içindeki tüm politikalar otomatik olarak uygulanır
  • Yeniden Kullanım: Aynı politika kombinasyonu birden fazla API Proxy’de kullanılabilir
  • Versiyonlama: Politika Grupları versiyonlanabilir ve farklı versiyonlar farklı API Proxy’lerde kullanılabilir
Detaylı Politika Grupları bilgisi için Politika Yönetimi sayfasına bakabilirsiniz.

​
Politika ve API Proxy İlişkisi

Politikalar API Proxy’lerin temel bileşenleridir:
  • API Proxy İçinde: Her API Proxy kendi politikalarını içerir. Bu politikalar API Proxy’ye özeldir.
  • API Proxy Grubu İçinde: Politika Grupları, birden fazla API Proxy’de kullanılabilen politika koleksiyonlarıdır.
  • Global Politikalar: Global olarak tanımlanan politikalar birden fazla API Proxy’de kullanılabilir.
Bir API Proxy’ye politikalar şu seviyelerde eklenebilir: 
API Proxy Group
├─ Group Pre-flow Politikaları
├─ Group Post-flow Politikaları
└─ Group Fault Handler Politikaları
    │
    └─ API Proxy
        ├─ Proxy Pre-flow Politikaları
        ├─ Proxy Conditional Politikaları
        ├─ Proxy Post-flow Politikaları
        └─ Proxy Fault Handler Politikaları
            │
            └─ Endpoint/Method
                ├─ Endpoint Pre-flow Politikaları
                ├─ Endpoint Post-flow Politikaları
                └─ Endpoint Fault Handler Politikaları
Politika uygulama seviyeleri ve çalışma sırası hakkında detaylı bilgi için Mesaj İşleme ve Politika Uygulama sayfasına bakabilirsiniz.

​
Politika Oluşturma ve Yönetimi

​
Politika Oluşturma

Politika oluştururken şu adımlar izlenir:
  1. Politika Türü Seçimi: Oluşturulacak politika türü seçilir
  2. Yapılandırma: Politika parametreleri form tabanlı arayüzle yapılandırılır
  3. Koşullar: İsteğe bağlı olarak koşullar tanımlanır
  4. Hata Mesajı Özelleştirme: Hata durumları için özel mesajlar tanımlanır
  5. Aktivasyon: Politika aktif hale getirilir
  6. Deployment: Değişikliklerin etkili olması için API Proxy redeploy edilir
Detaylı politika oluşturma ve yönetimi için Politika Yönetimi sayfasına bakabilirsiniz.

​
Politika Çalıştırma Sırası

Politikalar tanımlandıkları sırayla çalıştırılır. Bu sıra önemlidir çünkü:
  • Önce güvenlik kontrolleri yapılmalı
  • Sonra doğrulama yapılmalı
  • En son dönüştürme yapılmalı
Politika çalıştırma sırası şu şekildedir:
  1. API Proxy Group Pre-flow Politikaları
  2. API Proxy Pre-flow Politikaları
  3. Endpoint Pre-flow Politikaları
  4. Koşullu Politikalar
  5. Yönlendirme Adımı
  6. Post-flow Politikaları (İstek)
  7. Backend API İsteği
  8. Post-flow Politikaları (Yanıt)
  9. Fault Handler Politikaları (Hata durumunda)

​
En İyi Uygulamalar

  • Politikaları yeniden kullanılabilir olacak şekilde oluşturun
  • Mümkünse global politika tercih edin
  • Hata mesajlarını kullanıcı dostu hâle getirin
  • Politika koşullarını gereksiz yere karmaşıklaştırmayın
  • Değişiklik sonrası redeploy işlemini gerçekleştirin

​
Sonraki Adımlar

API Proxy Nedir?

API Proxy kavramını öğrenin

Mesaj İşleme ve Politika Uygulama

Mesaj akışı ve politika pipeline’ı öğrenin

Mesaj İşleme ve Politika Uygulama

Mesaj akışı ve politika uygulama sürecini öğrenin

Politikalar

Tüm politika türlerini inceleyin

Politika Yönetimi

Politika oluşturma ve yönetimi

Koşullu Politika Çalıştırma

Koşullu politika çalıştırmayı öğrenin