API اکوسیستم

(بخش: اکوسیستم و شبکه)

1) اهداف و اصول

• ادغام سریع و قابل پیش بینی (↓ زمان ادغام).
• قابلیت اطمینان و مقیاس پذیری (SLO، QoS، فشار پشتی).
• ایمنی و انطباق (حداقل حقوق، حسابرسی).
• تکامل بدون خرابی (نسخه, سازگاری, ficheflags).

اصول: قرارداد اول، به حداقل رساندن داده ها، idemotency، مشاهده به صورت پیش فرض، «دو سرعت» از نسخه های (هسته در مقابل تجربی).

2) طبقه بندی API

1. REST/HTTP - همزمان عملیات CRUD/فرمان، idempotency-کلید، صفحه بندی/نشانگر.
2. gRPC/QUIC - تاخیر کم، جریان، پروتکل های باینری.
3. رویدادها (Pub/Sub) - رویدادهای دامنه ("سپرده. '، پرداخت. '،' پل. '،' خطر. ').
4. Webhooks - اطلاعیه های معکوس با امضا و بازپرداخت.
5. GraphQL (محدود) - خواندن جمع آوری بیش از مغازه های تحقق یافته.
6. Admin/Meta - دایرکتوری ها، نسخه ها، وضعیت ها، کلید ها، سهمیه ها.

سطوح دسترسی: عمومی (روش های محدود/خواندن)، شریک (حوزه ها و سهمیه ها)، داخلی (خطوط خصوصی).

3) قراردادها و طرح ها

OpenAPI/AsyncAPI/Protobuf IDL یک منبع واحد حقیقت است.
قراردادهای داده - تست سازگاری، خطوط مدار، ممنوعیت «شکستن» فیلدها بدون MAJOR.
کاتالوگ ها: دارایی ها/شبکه ها، PSP/روش ها، مناطق/حوزه های قضایی، نسخه های SDK، پرچم های قابلیت.

حداقل قرارداد REST (قطعه OpenAPI)

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 }

رویدادها (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) نسخه و سازگاری

SemVer: سرگرد. جزئی است. پچ. MINOR/PATCH - سازگار با عقب MAJOR - نسخه های موازی ('/v1 '، '/v2') + آداپتورها.
سیاست رد: پنجره ≥ 90 روز، «دو خط» پشتیبانی، اطلاعیه های خودکار برای قراردادها.
پرچم ویژگی: فعال/غیر فعال کردن زمینه/روش های منطقه/شریک.
مذاکره توانایی: اعلام پروفایل های پشتیبانی شده هنگام دست دادن.

5) Idempotence، سفارشات و نشانگر

Idempotency-کلید برای دستورات (ایجاد/لغو)، کلید TTL ≥ 72 ساعت.
دقیقا یک بار معنایی از طریق صندوق پستی/صندوق ورودی و مصرف کننده idempotent.
صفحه بندی توسط نشانگر: 'next _ cursor'، مقاومت در برابر درج/حذف.
مرتب سازی و فیلترها پایدار هستند، به وضوح مستند شده است.

6) امنیت و اعتماد

mTLS (service↔service)، پین کردن سرتس و چرخش کلید.
OAuth2/OIDC (اعتبار مشتری، JWT با TTL کوتاه)، PoP/DPoP برای اتصال به کانال.
امضای Webhook (NMAS/نسخه کلید/زمان)، حفاظت از تکرار.
RBAC/ABAC و PoLP: حوزه، org_id/tenant_id، محدودیت در شی/عملیات.
حداقل DLP/PII: ممنوعیت PII در برچسب ها/سیاهههای مربوط، نشانه گذاری شناسه ها.
محدودیت نرخ و WAF: در هر سازمان/مسیر/منطقه، حفاظت از سوء استفاده.

سیاست کلید نمونه (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) سهمیه، QoS و فشار پشتی

کلاس های QoS: P0 (پرداخت/پل/نهایی)، P1 (محصول)، P2 (فله/آرشیو).
سهمیه ها/محدودیت ها: RPS، درخواست های توافق، بایت/ثانیه، موضوع/حزب برای رویدادها.
کنترل پذیرش: رد اولیه درخواست های «گران»، گارد پرس و جو سنگین.
فشار پشتی: نشانه ها/اعتبارات، صف با DLQ، با jitter تکرار می شود.

سیاست سهمیه بندی

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

8) قابلیت مشاهده: SLI/SLO، معیارها، ردیابی

• p95/99 تاخیر по маршрутам، میزان موفقیت، خطا در بودجه، p95 صف تاخیر، Freshness webhooks، موفقیت تحویل٪.
• انطباق قرارداد% (طرحوارهها/امضاها).
• وب سایت مجدد/کاهش یافته٪.

SLO: P0 p95 ≤ 400 ms، در دسترس بودن ≥ 99. 95%; تحویل وب سایت p95 ≤ 2 с ؛ رویدادهای طراوت p95 ≤ 60 с.

معیارها: هیستوگرام تاخیر، کدهای خطا، اندازه پاسخ ها، RPS، هر مستاجر.
ردیابی: end-to-end 'trace _ id' (edge → gateway → service → DB → event/webhook).
سیاهههای مربوط: ساختار یافته، بدون PII، همبستگی با 'request _ id'.

9) الگوهای انتشار بدون خرابی

آبی سبز/قناری با دروازه های SLO و خروجی بیرونی.
تکامل طرح اول: فقط اضافه کردن زمینه ها، آداپتورها برای مشتریان قدیمی.
مهاجرت پایگاه داده Zero-downtime: DDL آنلاین، مبدل های دو طرفه.
کنترل تغییر: زمان بندی، حسابرسی و رجیستری سازگاری.

10) کاتالوگ و ثبت نام

API/نسخه ثبت نام

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)
);

کاتالوگ رویداد

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

کلید/حوزه

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

11) تست و انطباق با قراردادها

تست های قرارداد: تولید مشتری، اعتبار سنجی طرح، negative-_cases.
تست رویداد تکرار: مقاومت در برابر تکرار/مرتب سازی مجدد.
هرج و مرج/آزمون لات: از دست دادن/تزریق jitter، stor آهسته است.
تست های امنیتی: امضاهای وب هوک، چرخش کلید، حملات پخش مجدد.
پروفایل های عملکرد: SLA سنبله، مسیرهای داغ، پل DA/وابستگی.

12) نمونه هایی از رابط

کتابهای وب (امضا و 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 (جمع آوری خواندن، فقط خواندن)

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

gRPC (جریان رویداد)

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

13) فرآیندها و نقش ها

مالک API - قرارداد/نسخه/SLO/سهمیه.
امنیت - کلید/امضا/حسابرسی/DLP.
SRE/Ops - داشبورد، هشدار، ظرفیت.
موفقیت شریک - onboarding، محدودیت ها، phicheflags.
انطباق - حوزه های قضایی، تحریم ها، گزارش ها.

14) داشبورد

API هسته: تاخیر/خطا/RPS توسط مسیر و چادر.
Webhooks: تحویل p95، تلاش مجدد، قطره، امضا.
رویدادها: طراوت، تاخیر، سلامت مصرف کننده، DLQ.
امنیت: کلید انقضا، امضا، درخواست های رد شده.
حکومت: نسخه های فعال/مستهلک، سازگاری قرارداد.

15) حوادث کتاب بازی

A. رشد P95 تاخیر P0

1. فعالسازی اولویت P0 و P2-throttle ؛ 2) دروازه های مقیاس ؛

2. بخشی از خواندن را به حافظه پنهان تغییر دهید 4) تجزیه و تحلیل مسیرهای «داغ».

B. تحویل webhook قطره

1. بررسی امضا/ساعت تغییر، 2) افزایش retrays/timeouts،

2. روشن کردن دسته، 4) به طور موقت به نقطه پایانی گلوله تغییر دهید.

C. قراردادهای رانندگی

1. «حالت سخت» را فعال کنید،

2. اطلاع تولید کننده، 3) انتشار آداپتور، 4) پس از مرگ، به روز رسانی linters.

D. کلید/cert سازش

1. لغو/چرخش، 2) پخش وب سایت، 3) حسابرسی، 4) اطلاع شرکای.

E. تکرار/انفجار

1. بررسی Idempotency-کلید/TTL, 2) تقویت deadup, 3) محدود کردن «پر سر و صدا» منبع.

16) چک لیست پیاده سازی

1. قراردادها را توصیف کنید (OpenAPI/AsyncAPI/IDL)، شامل خطوط و CI.
2. پیکربندی auth (OAuth2/OIDC، mTLS)، امضاهای webhook، چرخش کلید.
3. quota/QoS/limits, heavy-query-guard و backpressure را وارد کنید.
4. افزایش قابلیت مشاهده: SLI/SLO، آهنگ، داشبورد، هشدار.
5. سازماندهی انتشار: canary/blue-green, schema-first migrations.
6. دایرکتوری version/event/key را شروع کرده و فرآیندها را مستهلک کنید.
7. انجام آزمون هرج و مرج/perf/امنیت، ترتیب playbooks.
8. به طور منظم اصلاح داده ها به حداقل رساندن و انطباق قانونی.

17) واژه نامه

قرارداد اول - طراحی API از طریق قراردادهای رسمی به کد.
Idempotency-Key - کلیدی که باعث می شود عملیات با خیال راحت تکرار شود.
AsyncAPI - مشخصات رابط های رویداد.
QoS - کیفیت خدمات/کلاس اولویت.
DLQ - «صف مرده» برای پیام های مشکل.
Error budget burn - میزان «سوزاندن» بودجه خطا نسبت به SLO.

خط پایین: API اکوسیستم مجموعه ای از نقاط پایانی نیست، بلکه یک سیستم مدیریت شده از قراردادها، امنیت، سهمیه ها و قابلیت مشاهده است. با پیروی از این چارچوب، اکوسیستم یکپارچه سازی سریع، SLO های قابل پیش بینی و تکامل ایمن بدون خرابی - از لایه شبکه و احراز هویت به جریان رویداد و گزارش.