Politika Nedir?

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)

bilgi

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ı

Pre-flow Politikaları

İstek backend'e gönderilmeden önce çalışan politikalar:

• Kimlik doğrulama
• Yetkilendirme
• Rate limiting
• Mesaj doğrulama

Koşullu Politikalar

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

Yönlendirme Adımı

İsteğin backend'e yönlendirildiği adım:

• Upstream target seçimi
• Load balancing
• Failover

Post-flow Politikaları

Backend'den yanıt geldikten sonra çalışan politikalar:

• Yanıt dönüştürme
• Maskeleme
• Loglama
• Header ekleme

Fault Handler Politikaları

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 Politika	Local Politika
Birden fazla API Proxy'de kullanılabilir	Sadece bir API Proxy'de kullanılır
Merkezi yönetilir	Proxy bazında yönetilir
Bir kez güncellenir, tüm kullanımlar etkilenir	Her proxy için ayrı güncelleme gerekir
Yeniden kullanılabilirliği yüksek	Yeniden kullanılabilirliği düşük

Politika Uygulama Noktaları

Politikalar üç farklı seviyede uygulanabilir:

Uygulama Noktası	Açıklama
API Proxy Grubu	Bir gruptaki tüm API Proxy'lere uygulanır
API Proxy	Belirli bir API Proxy içindeki tüm metot/endpoint'lere uygulanır
Metot/Endpoint	Yalnı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:

Alan	Açıklama
HTTP Status Code	Varsayılan sistem kodu
Error Code	Varsayılan hata kodu
Original Message	Varsayılan hata mesajı
Customized HTTP Status Code	Farklı bir HTTP durum kodu döndürülür
Customized Error Code	Farklı 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.

Hata Açıklamaları (Tooltip)

Her hata mesajı satırında, Original Message alanının yanında bir bilgi ikonu (info-circle) bulunur. Bu ikonun üzerine gelindiğinde ilgili hatanın ne zaman oluştuğuna dair kısa bir açıklama tooltip olarak gösterilir. Bu sayede hangi durumda hangi hatanın tetiklendiğini hızlıca anlayabilirsiniz.

Satır Bazlı Özel Hata Mesajı Oluşturucu (Per-Error Custom Message Builder)

Mevcut inline alanlarla (Customized HTTP Status Code, Customized Error Code, Customized Error Message) yapılan basit özelleştirmelerin ötesinde, her hata mesajı satırı için ayrı ayrı şablon tabanlı özel hata mesajı oluşturucu tanımlayabilirsiniz.

Hata mesajı satırının sonundaki Customize (cark ikonu) butonuna tıkladığınızda bir dialog açılır. Bu dialog'da aşağıdaki alanlar bulunur:

Alan	Açıklama
Toggle	Özel hata mesajı oluşturucuyu etkinleştirir veya devre dışı bırakır
Kullanılabilir Değişkenler	error, request, message, dateTime kategorilerinde değişkenler accordion olarak listelenir. Clipboard'a kopyalanıp template'e yapıştırılabilir
Code Editor	Mesaj şablonu (JSON formatında). #{...} yer tutucuları kullanılabilir
Content Type	Yanıtın Content-Type değeri. Varsayılan: application/json;charset=utf-8
HTTP Status Code	Yanıtın HTTP durum kodu. Boş bırakılırsa hata tipine göre otomatik atanır

Bu özellik, politika düzeyindeki genel şablon yerine belirli bir hata tipi için daha spesifik bir yanıt oluşturmanızı sağlar.

Hata Mesajı Öncelik Sırası

Bir hata oluştuğunda Gateway aşağıdaki öncelik sırasına göre yanıt belirler:

Öncelik	Kaynak	Açıklama
1 (En yüksek)	Hata satırı bazlı özel mesaj şablonu	Belirli bir hata tipi için tanımlanan şablon tabanlı özel mesaj
2	Politika geneli özel mesaj şablonu	Politika genelinde tanımlanan şablon tabanlı özel mesaj
3	Hata yanıt kuralları	Koşul bazlı yanıt kuralları — istek bilgilerine göre farklı hata yanıtları döndürme
4	Hata satırı bazlı alan özelleştirmesi	Satır bazlı Özelleştirilmiş Mesaj, Özelleştirilmiş Hata Kodu, Özelleştirilmiş HTTP Durum Kodu alanları
5	Platform geneli hata mesajı özelleştirmesi	Sistem Ayarları > Hata Mesajları sayfasından yapılan özelleştirme
6 (En düşük)	Varsayılan hata mesajı	Sistem tarafından tanımlanan varsayılan hata mesajı

uyarı

Üst öncelikli bir kaynak tanımlıysa, alt öncelikliler değerlendirilmez. Örneğin bir hata satırı için özel mesaj şablonu aktifse, politika genelindeki şablon, hata yanıt kuralları veya satır bazlı alan özelleştirmeleri dikkate alınmaz.

bilgi

Hata mesajı yapılandırma sisteminin tüm katmanları, iş akışı ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

Şablon Tabanlı (Dinamik) Hata Mesajları

Hata durumlarında döndürülen mesajları tamamen özelleştirebilirsiniz. Serbest metin yazabileceğiniz şablon alanında, istek ve hata bilgilerini otomatik olarak mesaja dahil etmek için #{...} formatında yer tutucular kullanabilirsiniz.

Örnek şablon: Hata oluştu: #{error.defaultErrorCode} - İstek yolu: #{request.uri}

Kullanılabilir bilgi grupları (toplamda birçok yer tutucu):

Grup	Örnek yer tutucular
Hata bilgileri	Hata kodu, mesaj, HTTP status
İstek bilgileri	HTTP method, URI, IP adresi, sorgu parametreleri
Zaman bilgileri	Tarih, saat, timestamp
API bilgileri	API Proxy ID ve ismi
Mesaj bilgileri	Correlation ID

HTTP yanıt ayarlarından status kodunu (örn. 400, 500, 503) ve Content-Type değerini (JSON, XML, plain text) özelleştirebilirsiniz.

Şablon tabanlı hata mesajları hem politika genelinde (tüm hatalar için tek şablon) hem de satır bazında (belirli bir hata tipi için ayrı şablon) tanımlanabilir.

Kullanım alanları: Global politikalar, API Proxy, Yönlendirme (Routing), İş Kuralı STOP aksiyonu.

Örnek (İş Kuralı STOP):

Şablon:

API çağrınız başarısız oldu.
Hata Kodu: #{error.defaultErrorCode}
Zaman: #{dateTime.formattedText}
İstek ID: #{message.correlationId}

Sonuç örneği:

API çağrınız başarısız oldu.
Hata Kodu: BUSINESS_RULE_STOP
Zaman: 2024-01-29 14:30:45
İstek ID: 12345-67890-abcde

not

Bu özellik isteğe bağlıdır. Mevcut hata mesajlarınız aynen çalışmaya devam eder.

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

bilgi

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ı

bilgi

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

bilgi

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