عملیات API

(بخش: عملیات و مدیریت)

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

API «لایه عملیاتی» اکوسیستم است: هر چیزی که از طریق یک قرارداد خودکار نباشد، به کار دستی و ریسک تبدیل می شود.

• قرارداد اول: اولین مشخصات (OpenAPI/JSON Schema/AsyncAPI)، سپس پیاده سازی.
• امن به طور پیش فرض: محدوده حداقل، TTL کوتاه، متقابل TLS/امضا.
• قابل مشاهده: ردیابی پایان به پایان و معیارهای SLA.
• Idempotent: پخش امن.
• سازگار با عقب: تکامل بدون «شکستن» تغییرات.
• Auditable: حقایق تایید شده رمزنگاری (رسید).

2) قرارداد و مدل (مرجع)

OpenAPI برای درخواستهای همگامسازی ؛ AsyncAPI برای رویدادها/webhooks.
فیلدهای مورد نیاز در هر منبع عبارتند از «id», «version», «created _ at», «updated _ at», «tenant», «region», «trace _ id».

نمونه ای از یک قطعه قرارداد

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) احراز هویت، مجوز، حوزه

OAuth2/OIDC برای کاربران/شرکای مشتری-اعتبار/JWT для S2S.
حوزه ها/نقش منابع: "پرداخت ها. نوشتن کاتالوگ. خواندن، حسابرسی. صادرات ".
ReBAC: دسترسی «با مالکیت» (مستاجر/حساب/زیر حساب).
اسرار JIT: نشانه های کوتاه مدت، اتصال دستگاه/زیر شبکه/منطقه.
وضعیت دستگاه & mTLS برای عملیات بحرانی (پرداخت، کلید).

4) idempotence و «دقیقا یک بار»

Idempotency-Key (سرآیند) + dedup by '(کلید، حساب، مسیر)' در پنجرۀ TTL.
Outbox/CDC برای ارسال رویدادها - تحویل تضمین شده.
دقیقا یک بار اثرات: عوارض جانبی از طریق یک مجله معامله دستگیر می شوند ؛ تکرار منجر به همان «رسید» («receipt _ hash») می شود.
سیاست های مجدد: عقب نشینی نمایشی، لرزش، حداکثر پنجره ها.

5) محدودیت ها، سهمیه ها، اولویت بندی

محدودیت نرخ: در هر کلید/مستاجر/مسیر/منطقه ؛ «نرم» (429) و «سخت» (قطع).
سهمیه/بودجه: ماهانه/روزانه کلاه، webhooks 'QuotaCapReached'.
استفاده منصفانه: اولویت مستاجران بر اساس سطح خدمات (طلا/نقره/برنز).
بافر پشت سر هم: انفجار کوتاه بدون تخریب همسایگان.

6) صفحه بندی، فیلتر، نمونه

مبتنی بر مکان نما (دستور پایدار по 'created _ at, id')، 'page _ size' ≤ 1000.
نمونه های برش زمان («از»، «به»، «علامت») برای سیاهههای مربوط/معاملات.
فیلتر کردن DSL: поля لیست سفید, '? status =... & tenant =... & region =...'.
نکات سازگاری: 'snapshot _ at '/' as _ of' برای گزارش API ها.

7) نسخه و سازگاری

SemVer: 'v1', 'v1. 1 '(پسوند)،' v2 '- فقط در مسیرهای جدید/فضای نام.
قوانین تکامل: فقط فیلدها/مقادیر را اضافه کنید، «deprecate → remove» را از طریق پنجره اضافه کنید.
تست های سازگاری: «قراردادها به عنوان آزمون» (مصرف کننده محور).

8) رویدادها، وب سایت ها و رسید ها

AsyncAPI تم ها/payload/امضاها را توصیف می کند.

عنوان: HMAC/EdDSA، هدر 'X-Signature'، 'X-Nonce'، 'X-Timestamp' (پنجره باریک)

رسید: 'receipt _ hash' و امضای DSSE در رویدادهای بحرانی (پرداخت، تغییرات RTP/limit، لیست قیمت).
Retrai و dedup: idempotency با توجه به 'idempotency _ key '/' event _ id'.
DLQ/قرنطینه: گزارش های نامعتبر/تکراری با علل.

9) قابلیت مشاهده و کیفیت

ردیابی: ردیابی اجباری _ id/span _ id از طریق gateway/business events/webhooks.
معیارها: در دسترس بودن، p50/p95/p99، نرخ خطا، نرخ مجدد، هزینه هر 1k.
سیاهههای مربوط: ساختار، بدون اسرار/PII ؛ 'tenant/region/version' برچسب ها.
SLO/هشدار: شرایط SLO گرا و خودکار runes (مکث/دوباره مسیر/برگشت).

10) خطاها و معانی وضعیت

2xx - success (202 برای عملیات آسنکرون)

4xx - خطای مشتری (422 - اعتبار سنجی، 409 - درگیری/idempotency، 429 - محدودیت).

۵xx - مشکلات موقت

بدنۀ خطا: "کد"، "پیام"، "ردیابی _ id"، "اشاره"، "سعی مجدد _ بعد از ؟ '.
UX برای شرکا: یک جدول از «چه کاری باید انجام شود» برای هر خطا.

11) سیاست به عنوان کد (OPA/ABAC)

مجوز متمرکز: «چه کسی/چه چیزی/کجا/چه زمانی/چرا».
سیاست در گیت، بررسی کد، آزمون CI (قبل از پرواز: "آیا سیاست اجازه می دهد ؟ »).
بررسی SoD: «ایجاد پرداخت» ≠ «تایید».

12) امنیت، حریم خصوصی، انطباق

به حداقل رساندن PII: نشانه گذاری/ماسک، دسترسی به اولیه تنها از طریق jabs تایید شده است.

اسرار: خرک/KMS، TTL کوتاه، چرخش ؛ ممنوعیت اسرار مشترک

رمزگذاری: mTLS/TLS 1. 3، AES-GCM در حالت استراحت، HSTS/PKP که در آن مناسب است.
صلاحیت آگاه - محلی سازی داده ها/کلید در هر منطقه.
سیاهههای مربوط به ممیزی: WORM، Merkle-slices، DSSE-signatures.

13) عملیات: SLI/SLO و داشبورد

• در دسترس بودن در هر مسیر/منطقه.
• تاخیر p95 (خواندن/نوشتن).
• موفقیت webhooks (رسید)، تاخیر تحویل.
• نرخ خطا/نرخ تلاش مجدد.
• هزینه هر درخواست 1k و خروج.

SLO (مثال): 99. 95٪ در دسترس بودن ؛ p95 ≤ 120/250 میلی ثانیه ؛ وب سایت ≥ 99 5 ٪/5 دقیقه ؛ P1 MTTR ≤ 60 دقیقه

14) مدیریت تغییر (انتشار/بازپرداخت)

آبی سبز/قناری برای دروازه ها و مسیرهای بحرانی.
Ficheflags برای رفتار بدون آزادی.
Expand → Migrate → قرارداد برای طرحوارهها و بار.
Руны: انتشار برگشت, غیر فعال کردن پرچم, دوباره مسیر, کش خیط و پیت کردن.
مصنوعات: تصاویر/مانیفست های امضا شده، رجیستری نسخه.

15) SDK، مشتریان، sandboxes

SDK های رسمی (TS/Java/Python/Go) با همان خطا و معانی مجدد.
محیط های Sandbox با کلید های تست/گواهینامه ها و شبیه ساز PSP/KYC/ارائه دهنده محتوا.
تست های قرارداد در CI SDK، سازگاری شبانه گنجانده شده است.

16) مدل داده (ساده شده)

'api _ key' {شناسه، مستاجر، حوزه []، ttl، created_by}'

'rate _ plan' {مستاجر، سهمیه {مسیر → کلاه}، پشت سر هم، اولویت} '

'request _ log' '{ردیابی _ id، مسیر، بازیگر، idempotency_key?، وضعیت، latency_ms، منطقه، cost_unit}'

'webhook _ receipt' {event _ id, endpoint, status, تلاش، receipt_hash، امضا} '

'policy' {نسخه، قوانین، امضا کننده، dsse} '

17) RACI

18) معیارهای کیفیت

رانش قرارداد: 0 «شکستن» تغییرات بدون مستهلک.
میزان خطا: ≤ 0. 01%.
موفقیت وب سایت: ≥ 99. 5٪، تاخیر p95 ≤ 60 ثانیه.
Auth Fail vs سوء استفاده: سهم بلوک های مخرب، سر و صدا ≤ سطح هدف.
Cost/1k: کنترل توسط مسیرها و مناطق (بودجه/کلاه هشدار).
تصویب SDK: سهم ترافیک از طریق SDK های رسمی.

19) کتاب های حادثه

Spike 429/limits: افزایش کلاه برای طلا، کاهش کلید های «پر سر و صدا»، ارتباط با یک شریک.
WebhookLag: کارگران/دسته ها را افزایش می دهد، صف ها را اولویت بندی می کند، به طور موقت وب سایت های اختیاری را خاموش می کند.
PriceMismatch (کاتالوگ/FX/مالیات): آشتی نسخه, ناتوانی نیروی کش, عقبگرد مصنوع, جبران خسارت.
قطع PSP: سوئیچینگ مسیر، قرنطینه معاملات «خاکستری»، پخش.
API-key سازش: یادآوری فوری، چرخش، حسابرسی 30 روز گذشته.

20) ویژگی های iGaming/fintech

RTP/محدودیت های API: تنها مصالح و نسخه های مشخصات; تغییرات - با رسید.
پرداخت/پرداخت: 202 + امضا webhooks ؛ idemotency کلید را سفارش دهید.
وابسته: تبدیل dedup, سپردن اختلافات, گزارش امضا.
بازی مسئول: افشای «guardrails API» برای محدودیت ها و رویدادهای RG.

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

• قرارداد توصیف شده (OpenAPI/AsyncAPI)، اعتبار سنجی CI و تست های مصرف کننده.
• پیکربندی OAuth2/OIDC، حوزه ها، اسرار JIT و mTLS برای مسیرهای بحرانی.
• Idempotency، retrai، DLQ و قرنطینه معرفی شده است.
• کلاه/سهمیه/اولویت ها و هشدارها.
• صفحه بندی مکان نما، «as _ of» نمونه های سازگار.
• سیاست نسخه و استهلاک.
• Webhooks با امضا/رسید، پخش و dedup.
• ردیابی/متریک/سیاهههای مربوط، SLO و runes.
• گزارش های WORM، امضاهای DSSE، برش های Merkle.
• SDK، sandbox، شبیه سازی، نمونه کد و نحوه استفاده.

22) سوالات متداول

چرا 202 برای عملیات طولانی ؟

به منظور نگه داشتن اتصال و ارائه یک retray/دریافت قابل اعتماد از طریق webhook.

آیا به هر دو OpenAPI و AsyncAPI نیاز دارید ؟

بله: همگام سازی برای دستورات/درخواست ها، async برای رویدادها/مذاکرات دولت.

چگونه از شکستن تغییرات جلوگیری کنیم ؟

اضافه کردن فقط قانون, مستهلک → مشاهده → حذف, قرارداد آزمون مشتری.

رسیدها را کجا ذخیره کنیم ؟

در یک منطقه WORM با امضا ؛ 'receipt _ hash' به مشتری بازگردانده می شود و بر اساس درخواست بررسی می شود.

خلاصه: عملیات از طریق API نظم و انضباط قرارداد و عملیات: مدل دسترسی دقیق و idempotency, محدودیت ها و نسخه, مشاهده و SLO, امضا و رسید. سندباکس ها و SDK ها را اضافه کنید - و شرکا به سرعت، ایمن و قابل پیش بینی ادغام می شوند و مشاغل بدون از دست دادن کیفیت یا انطباق مقیاس می شوند.