> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Politika Nedir?
> Politika, API Proxy'lerde mesajlara uygulanan işlemleri tanımlayan yapılandırılabilir bileşenlerdir. Politikalar, güvenlik, doğrulama, dönüştürme, trafik yönetimi gibi çeşitli işlevleri sağlar ve kod yazmadan form tabanlı arayüzlerle yapılandırılır.
## 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.
Politikalar form tabanlı arayüzlerle yapılandırılır. Kod yazmaya gerek yoktur.
Politikalar global olarak tanımlanabilir ve birden fazla API Proxy'de kullanılabilir.
Politikalar koşullara bağlı olarak çalıştırılabilir.
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:
```mermaid theme={null}
sequenceDiagram
participant Client as 👤 İstemci
participant Gateway as 🚪 API Gateway
participant PreFlow as 🛡️ Pre-flow Politikaları
participant Routing as 🎯 Yönlendirme
participant Backend as 🖥️ Backend API
participant PostFlow as 📤 Post-flow Politikaları
participant FaultHandler as 🚨 Fault Handler
Client->>Gateway: HTTP İsteği
Gateway->>PreFlow: Pre-flow Politikaları
Uygulanır
Note over PreFlow: Politika Seviyeleri:
Group → Proxy → Endpoint
Politika Türleri:
Güvenlik, Trafik Yönetimi,
Doğrulama, Dönüştürme
PreFlow->>Routing: Yönlendirme Adımı
Routing->>Backend: İşlenmiş İstek
Backend'e İletilir
alt Başarılı Yanıt
Backend->>PostFlow: Yanıt Döner
Note over PostFlow: Post-flow Politikaları:
Dönüştürme, Zenginleştirme,
Maskeleme, Loglama
PostFlow->>Gateway: İşlenmiş Yanıt
Gateway->>Client: HTTP Yanıtı
else Hata Durumu
Backend-->>Routing: ❌ Hata Oluştu
Routing->>FaultHandler: Fault Handler
Politikaları
Note over FaultHandler: Hata Yakalama,
Hata Mesajı Dönüştürme,
Özelleştirilmiş Hata Yanıtı
FaultHandler->>Gateway: Hata Yanıtı
Gateway->>Client: HTTP Hata Yanıtı
end
Note over Client,Gateway: İşlem Tamamlandı
```
## 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ı
* OAuth2
* OIDC
* JWT
* Basic Authentication
* Digest Authentication
* mTLS
* IP Whitelist/Blacklist
* API Key
* Role-based Access Control
### Trafik Yönetimi Politikaları
* API Bazlı Daraltma
* API Bazlı Kota
* Zaman Kısıtlaması
* Yük dengeleme stratejileri
* Failover
### Mesaj İşleme Politikaları
* JSON Schema Doğrulama
* XML Schema Doğrulama
* Min/Max Mesaj
* JSON Dönüştürme (Jolt)
* XML Dönüştürme (XSLT)
* Plain Text
### Mesaj Zenginleştirme ve İş Mantığı Politikaları
* Header ekleme
* Veri ekleme
* Script (Groovy/JavaScript)
* Koşullu iş mantığı
* Aksiyon zinciri
* Veri manipülasyonu
* Harici API çağrıları
* Veri çekme
* Entegrasyon
* Şifreleme/Şifre Açma
* Dijital İmza
* Redaction (Maskeleme)
Tüm politika türleri ve detaylı açıklamaları için [Politikalar](/tr/develop/politikalar/api-bazli-daraltma.mdx) 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 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](/tr/concepts/temel-kavramlar/mesaj-isleme-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ı](/tr/admin/system-settings/hata-mesajlari) sayfasından yapılan özelleştirme |
| 6 (En düşük) | Varsayılan hata mesajı | Sistem tarafından tanımlanan varsayılan hata mesajı |
Ü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.
Hata mesajı yapılandırma sisteminin tüm katmanları, iş akışı ve senaryo örnekleri için [Hata Mesajı Yapılandırma Rehberi](/tr/concepts/temel-kavramlar/hata-mesaji-yapilandirma) 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)](/tr/develop/yonlendirme/http-yonlendirme), [İş Kuralı STOP](/tr/develop/politikalar/is-kurali) 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
```
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
Detaylı Politika Grupları bilgisi için [Politika Yönetimi](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi) 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](/tr/concepts/temel-kavramlar/mesaj-isleme-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](/tr/develop/api-proxy-konfigurasyonu/politika-yonetimi) 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 kavramını öğrenin
Mesaj akışı ve politika pipeline'ı öğrenin
Mesaj akışı ve politika uygulama sürecini öğrenin
Tüm politika türlerini inceleyin
Politika oluşturma ve yönetimi
Koşullu politika çalıştırmayı öğrenin