چک لیست ادغام API

0) بررسی سریع (چه کسی چه کاری انجام می دهد)

• ادغام مالک اختصاص داده شده
• در تماس با مخاطبین (24 × 7/ساعت کار) تجویز می شوند
• توافق SLO/SLA و پنجره پشتیبانی انتشار
• صفحه وضعیت و کانال حادثه (ایمیل/slack/webhook)

1) دسترسی ها، محیط ها، نسخه ها

• ماسهبازی/مرحله بندی/تولید دسترسی
• نسخه API تایید شده: '/v1 '/هدر 'X-API-نسخه'
• اجازه قوانین IP و شبکه پیکربندی شده است
• ساعت و TZ: همه زمان ها در UTC، هماهنگ سازی NTP
• SemVer SDK/سازگاری مشتری و نسخه ماتریس تایید شده است

2) احراز هویت و نشانه

• مکانیسم OAuth2 اعتبار مشتری/کد Auth + PKCE/API Key/mTLS موافقت کرد
• دسترسی به رمز طول عمر و چرخش تازه کردن رمز پیکربندی شده است
• برای کلید API: راز یک بار نشان داده شده است، ذخیره شده در مدیر مخفی
• JWKS/JTI/' بچه 'چک، ساعت در ± 5 دقیقه
• «مجوز» هدر وارد نشده (تجدید نظر)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) امنیت و حریم خصوصی

• TLS 1. 2 +/HSTS، mTLS اختیاری
• به حداقل رساندن PII: ما ارسال تنها آنچه که ما نیاز داریم، ماسک در سیاهههای مربوط
• سیاست حفظ و نگهداری (GDPR/DSAR) مستند شده است
• چرخش مخفی: کلید فعال/بعدی، برنامه ریزی مجدد
• ضد سوء استفاده: Captcha/سرعت کلید/محدودیت ثبت نام

4) محدودیت ها، سهمیه ها و عقب نشینی

• اعلام 'X-RateLimit- '/' X-Quota-' هدر
• مشتری به 429 و «Retry-After» احترام می گذارد
• Retrays فقط برای 5xx/408/429، عقب نشینی نمایشی + لرزش
• تلاش مجدد/محدودیت زمانی مجموعه (به عنوان مثال ≤ 5 تلاش مجدد, ≤ 60C مجموع)

5) ناتوانی و درگیری

• تمام عملیات نوشتن با «Idempotency-Key» ارسال می شود (TTL ≥ 24-72 ساعت)
• تعارض تکراری → 409 IDEMP_REPLAY به کار گرفته
• ETag/' If-Match 'برای به روز رسانی های رقابتی فعال شده است (در صورت موجود بودن)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) صفحه بندی و دلتاهای افزایشی

• صفحه بندی مکان نما/keyset استفاده می شود ('next _ cursor'، 'has _ more')
• مرتب سازی پایدار (updated_at، id) 'مستند شده است
• آپلود افزایشی: علامت یا تغییر نشانه
• همپوشانی (همپوشانی 1-2 دقیقه) و dedup توسط '(id, version/seq)'

7) فرمت خطا و تشخیص

• فرمت یکنواخت برنامه/مشکل + json (RFC 7807)
• پشتیبانی زمینه: «خطا _ کد»، «ردیابی _ id»، «قابل بازیابی»، «جزئیات»
• نقشه خطا و اقدامات مشتری شرح داده شده (runbook)

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8) Webhooks: تصدیق و تکرار

• تایید موفقیت - هر 2xx ؛ ACK سریع پس از درخواست
• Подпись HMAC («X-Signature: sha256 =»...)، «X-Webhook-Id»، «X-Retry»
• سیاست Retray: عقب نشینی + jitter، تا 24-72 ساعت
• DLQ + پخش: در دسترس و معتبر
• ذخیره سازی Dedup در گیرنده، TTL ≥ پنجره های retray

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

• قلاب OpenTelemetry در مشتری/SDK فعال است
• ردیابی زنجیره ای _ id/X-Request-ID همبستگی
• Дашборды: «requests _ total»، «errors _ total {status}»، «latency _ p95»، «retry _ count»، «429 _ rate»
• هشدارها: اسپایک 5xx/429، افزایش p95، کاهش میزان موفقیت، تاخیر webhook

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) عملکرد و ثبات

• استخر اتصال، زنده نگه داشتن، HTTP/2/3 در صورت امکان
• فشار پشتی، صف مشتری «متورم» نیست
• سیاست های مدار شکن/timeout/fallback پیکربندی شده است
• تست بار: پشت سر هم 10 ×، اتصالات طولانی، شروع سرد

11) داده ها، ارزها، زمان

• فرمت ها: ISO-8601 ساعت محلی UTC تنظیم شده اند، پول - رشته های اعشاری/واحدهای جزئی، مناطق به محیط بستگی ندارد
• رمزگذاری ها/زبان ها سازگار هستند (به عنوان مثال 'Accept-Language' برای پیامها اما 'error _ code' برای ماشین)
• گرد کردن/سیاست کمیسیون مستند شده است

12) آشتی

• آشتی روزانه/ساعتی با چک سام
• API/آپلود برای آشتی تست شده (CSV/JSON, مظاهر/هش)
• اختلافات - در بلیط با اشاره به «ردیابی _ id»

13) انطباق و جنبه های قانونی

• API شرایط استفاده پذیرفته (استفاده منصفانه/کنترل صادرات)
• PII/دارندگان داده ها - نقش ها و مناطق ذخیره سازی تعریف شده است
• اقدامات قانونی/حسابرسی حسابرسی فعال برای حوادث

14) پورتال مستندات و توسعه

• OpenAPI/AsyncAPI مرتبط هستند، نمونه هایی از «کپی چسباندن» وجود دارد
• SDK (TS/Py/Java/Go/.NET) - نسخه ها سازگار هستند، Cookbook در دسترس است
• زمین بازی Try-it کار می کند، کلید های شن و ماسه فعال هستند
• تغییرات/مقررات/نقشه راه در پورتال قابل مشاهده است

15) تست: عملکردی، منفی، هرج و مرج

عملکردی

• CRUD/سناریوهای کلیدی گذشت (مسیر مبارک)
• صفحه بندی/مکان نما/دلتاهای افزایشی

منفی

• 401/403/404/409/422/429/5xx و پردازش مجدد
• امضای webhook نادرست، نشانه منقضی شده، بدن بزرگ

هرج و مرج

• رها کردن رویدادهای 10-30٪، مرتب سازی مجدد، تاخیر 1-10 دقیقه
• غیر فعال کردن وابستگی ها (PSP/KYC) → خطاهای صحیح

16) پذیرش و راه اندازی (برو زندگی می کنند)

• PRR نهایی (بررسی آمادگی تولید) گذشت
• شامل قناری: 10٪ → 25٪ → 50٪ → 100٪
• بازگشت خودکار به سیگنال های SLO (خطاها/تاخیر/429)
• ماتریس تماس با حادثه و مسیر تشدید منتشر شده است
• عقب ماندگی CAPA پس از خلبان تولید شده است

17) عملیات و پشتیبانی

• Runbook/playbooks: «اسپایک 5xx», «429 storm», «webhook backlog», «timeout»
• گزارش های بودجه منظم SLO/خطا
• چرخش اسرار و کلید در یک برنامه
• نسخه افسردگی/برنامه مهاجرت توافق (تاریخ غروب آفتاب)

18) الگوهای مصنوعی

قالب Env-config

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

سیاست Retray (شبه)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) چک لیست نهایی «برای امضا»

• محیط/نسخه/کلید/allowlist آماده
• Auth/JWT/کلید/mTLS پیکربندی و آزمایش شده است
• محدودیت/سهمیه/retrays/idempotency اجرا شده است
• صفحه بندی/مکان نما/دلتاها بر روی داده ها کار می کنند
• Webhooks: امضا، تکرار، DLQ/پخش تایید شده است
• خطاهای 'مشکل + json'، 'ردیابی _ id' sticks به تمام سیاهههای مربوط
• داشبورد/هشدار جمع آوری شده، OTel را فعال کنید
• تست بار/منفی/هرج و مرج گذشت
• آشتی و گزارش همگرا، runbooks رسمی هستند
• PRR/canary/rollback-طرح آماده، در تماس با مخاطبین نشان داد

مجموع

این چک لیست جنبه های فنی، عملیاتی و انطباق ادغام API را پوشش می دهد. از طریق آیتم ها از بالا به پایین بروید، محدودیت های چک، idemotency و webhooks را خودکار کنید، قابلیت مشاهده و برنامه ریزی را فعال کنید - و راه اندازی شما قابل پیش بینی خواهد بود، بدون «شگفتی» در تولید.