Ekosistem API'si

(Bölüm: Ekosistem ve Ağ)

1) Hedefler ve ilkeler

• Hızlı, öngörülebilir entegrasyon (entegrasyon zamanı ↓).
• Güvenilirlik ve ölçeklenebilirlik (SLO, QoS, geri basınç).
• Güvenlik ve uyumluluk (minimum haklar, denetim).
• Arızasız evrim (sürümler, uyumluluk, ficheflags).

İlkeler: sözleşme-ilk, veri minimizasyonu, idempotency, varsayılan olarak gözlemlenebilirlik, sürümlerin "iki hızı" (çekirdek ve deneysel).

2) API taksonomisi

1. REST/HTTP - senkron CRUD/komut işlemleri, idempotency-key, pagination/cursors.
2. gRPC/QUIC - düşük gecikme süresi, akışlar, ikili protokoller.
3. Etkinlikler (Pub/Sub) - domain etkinlikleri ('deposit. ',' ödeme. ',' köprü. ',' risk. ').
4. Webhooks - imzalar ve geri izlemelerle bildirimleri tersine çevirir.
5. GraphQL (sınırlı) - materyalize vitrinler üzerinde okuma toplama.
6. Admin/Meta - dizinler, sürümler, durumlar, anahtarlar, kotalar.

Erişim düzeyleri: Genel (sınırlı yöntemler/okuma), İş Ortağı (kapsamlar ve kotalar), Dahili (özel konturlar).

3) Sözleşmeler ve planlar

OpenAPI/AsyncAPI/Protobuf IDL tek bir doğruluk kaynağıdır.
Veri Sözleşmeleri - uyumluluk testleri, devre hatları, MAJOR olmadan alanları "kırma" yasağı.
Kataloglar: varlıklar/ağlar, PSP/yöntemler, bölgeler/yetki alanları, SDK sürümleri, yetenek bayrakları.

Minimum REST sözleşmesi (OpenAPI parçası)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

Olaylar (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

4) Sürüm oluşturma ve uyumluluk

SemVer: 'Binbaşı. MINÖR. PATCH '. MINOR/PATCH - geriye dönük uyumlu; MAJOR - paralel sürümler ('/v1 ','/v2') + adaptörler.
Reddetme politikası: 90 gün ≥ pencere, "iki satır" destek, sözleşmeler için otomatik bildirimler.
Özellik Bayrakları: Alanları/yöntemleri bölgeye/iş ortağına göre etkinleştir/devre dışı bırak.
Yetenek Anlaşması: El sıkışırken desteklenen profilleri bildirme.

5) Idempotence, siparişler ve imleçler

Komutlar için Idempotency-Key (oluştur/iptal et), TTL tuşları ≥ 72 saat.
Giden/gelen kutusu ve idempotent tüketici aracılığıyla tam olarak bir kez semantik.
İmleçler tarafından sayfalama: 'next _ cursor', eklemelere/silmelere karşı direnç.
Sıralama ve filtreler kararlı, açıkça belgelenmiştir.

6) Güvenlik ve güven

mTLS (service↔service), setlerin sabitlenmesi ve tuş rotasyonu.
OAuth2/OIDC (istemci kimlik bilgileri, kısa TTL ile JWT), kanala bağlanmak için PoP/DPoP.
Webhook imzaları (NMAS/anahtar sürümü/saati), tekrarlama koruması.
RBAC/ABAC ve PoLP: kapsamlar, org_id/tenant_id, nesne/işlem sınırları.
DLP/PII minimizasyonu: Etiketlerde/günlüklerde PII yasağı, tanımlayıcıların tokenizasyonu.
Oran sınırları ve WAF: org/rota/bölge başına, kötüye kullanım koruması.

Örnek Anahtar Politikası (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) Kotalar, QoS ve geri basınç

QoS sınıfları: P0 (ödemeler/köprü/sonuçlandırma), P1 (ürün), P2 (toplu/arşiv).
Kotalar/sınırlar: RPS, concur-requests, bytes/sec, subject/party for events.
Kabul kontrolü: "pahalı" taleplerin erken reddi, ağır sorgu görevlisi.
Backpressure: belirteçler/krediler, DLQ ile kuyruklar, jitter ile retrays.

Kota Politikası

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) Gözlemlenebilirlik: SLI/SLO, metrikler, izler

• P95/99 gecikme süresi по маршрутам, Başarı Oranı, Hata bütçesi yanması, Kuyruk-gecikme p95, Tazelik webhooks, Teslimat başarısı %.
• Sözleşme Uyumluluğu % (şemalar/imzalar).
• Webhook yeniden deneme/düşürme %.

SLO: P0 p95 ≤ 400 ms, Kullanılabilirlik ≥ 99. 95%; Webhook teslimat p95 ≤ 2 с; Olaylar tazelik p95 ≤ 60 с.

Metrikler: gecikme histogramları, hata kodları, yanıtların boyutu, RPS, kiracı başına.
İzler: Uçtan uca 'trace _ id' (kenar, ağ geçidi, servis, DB, olay, webhook).
Günlükler: yapılandırılmış, PII olmadan, 'request _ id'ile korelasyon.

9) Kesinti süresiz sürüm kalıpları

Mavi-Yeşil/Kanarya SLO kapıları ve outlier-ejection ile.
Şema-ilk evrim: sadece alan ekleme, eski istemciler için adaptörler.
Sıfır kesinti veritabanı geçişleri: Çevrimiçi DDL, çift yönlü dönüştürücüler.
Değişiklik denetimi: Zaman kilidi, denetim ve uyumluluk kaydı.

10) Kataloglar ve kayıtlar

API/Sürüm Kaydı

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

Etkinlik Kataloğu

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

Anahtarlar/kapsamlar

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) Test ve sözleşmelere uygunluk

Sözleşme testleri: istemci oluşturma, şema doğrulama, negative-_cases.
Tekrarlama olay testleri: tekrarlama/yeniden sıralamaya karşı direnç.
Kaos/Lat testleri: kayıp/jitter enjeksiyonları, yavaş stor.
Güvenlik testleri: webhook imzaları, anahtar rotasyonu, tekrarlama saldırıları.
Performans profilleri: SLA sivri uçları, sıcak yollar, DA/bağımlılık köprüsü.

12) Arayüzlere örnekler

Webhooks (imza ve retrai)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (Toplu Okuma, Sadece Okuma)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (olay akışı)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) Süreçler ve roller

API Sahibi - Sözleşme/Sürüm/SLO/Kota.
Güvenlik - anahtarlar/imzalar/denetim/DLP.
SRE/Ops - panolar, uyarılar, kapasite.
Ortak Başarı - onboarding, limitler, phicheflags.
Uyum - yargı, yaptırımlar, raporlama.

14) Panolar

Çekirdek API: rota ve çadıra göre gecikme/hata/RPS.
Webhooks: teslimat p95, yeniden denemeler, düşmeler, imzalar.
Olaylar: tazelik, gecikme, tüketici sağlığı, DLQ.
Güvenlik: son kullanma anahtarları, imzalar, reddedilen istekler.
Yönetişim: aktif sürümler/kullanımdan kaldırmalar, sözleşme uyumluluğu.

15) Playbook olayları

A. p95 gecikme P0 büyümesi

1. P0 ve P2-throttle önceliğini etkinleştir; 2) ölçekli ağ geçitleri;

2. Okumaların bir kısmını önbelleğe alın 4) "sıcak" rotaların analizi.

B. Teslimat webhook bırakma

1. İmzaları/saat kaymasını denetleyin, 2) geri dönüşleri/zaman aşımlarını artırın,

2. Partileri açın, 4) geçici olarak mermi son noktasına geçin.

C. drift sözleşmeleri

1. "Katı mod'u etkinleştir,

2. Üreticiyi bilgilendirin, 3) adaptörü serbest bırakın, 4) ölümden sonra, astarları güncelleyin.

D. Anahtar/cert uzlaşma

1. İptal/döndürme, 2) webhook'ları tekrar oynatma, 3) denetim, 4) ortaklara haber verme.

E. tekrar et/patlama al

1. Idempotency-Key/TTL'yi kontrol edin, 2) deadup'ı güçlendirin, 3) "gürültülü" kaynağı sınırlayın.

16) Uygulama kontrol listesi

1. Açıklama sözleşmeleri (OpenAPI/AsyncAPI/IDL), linters ve CI içerir.
2. Auth (OAuth2/OIDC, mTLS), webhook imzalarını, tuş rotasyonunu yapılandırın.
3. Kotalar/QoS/limitler, ağır sorgu koruması ve geri basınç girin.
4. Gözlemlenebilirliği artırın: SLI/SLO, parçalar, gösterge panoları, uyarılar.
5. Yayınları düzenleyin: kanarya/mavi-yeşil, şema-ilk geçişler.
6. Version/event/key dizinini başlatın ve işlemleri kullanımdan kaldırın.
7. Kaos/perf/güvenlik testleri yapın, oyun kitapları düzenleyin.
8. Veri minimizasyonunu ve mevzuata uygunluğu düzenli olarak yenileyin.

17) Sözlük

Contract-first - Kodlamak için resmi sözleşmeler yoluyla API tasarımı.
Idempotency-Key - işlemi güvenli bir şekilde tekrarlayan bir anahtar.
AsyncAPI - olay arayüzlerinin belirtimi.
QoS - Hizmet Kalitesi/Öncelik Sınıfı.
DLQ - sorunlu mesajlar için "ölü kuyruk".
Hata bütçesi yakma - hata bütçesini SLO'ya göre "yakma" oranı.

Sonuç olarak: Ekosistem API'si bir dizi uç nokta değil, yönetilen bir sözleşme, güvenlik, kota ve gözlemlenebilirlik sistemidir. Bu çerçeveyi izleyerek, ekosistem hızlı entegrasyonlar, öngörülebilir SLO'lar ve kesinti olmadan güvenli bir evrim kazanır - ağ katmanından ve kimlik doğrulamasından olay akışlarına ve raporlamaya kadar.