تکنولوژی و زیرساخت → نسخه API

نسخه API

1) چرا شما به آن نیاز دارید

• کاهش خطر حوادث در طول انتشار،
• به شما اجازه می دهد تا برنامه های بهبود و ایمنی را برنامه ریزی کنید
• کسب و کار می دهد جدول زمانی قابل پیش بینی برای مهاجرت شریک.

2) طبقه بندی تغییرات

PATCH (not breaking): اصلاحات بدون تغییر قرارداد (اضافه کردن فیلدهای اختیاری، رفع اعتبارسنجی).
MINOR: پسوندهای سازگار با عقب (نقاط پایانی جدید، زمینه ها با پیش فرض).
MAJOR (شکستن): تغییر ساختار، معناشناسی یا حذف فیلدها/نقاط پایانی.

SemVer 'MAJOR توصیه می شود. جزئی است. PATCH برای مصنوعات (SDK/schemas)، در حالی که شماره API «خارجی» می تواند ساده شود (v1، v2).

3) مدل های نسخه REST

1. به یوری:

'GET/v1/payments/{ شناسه}'

مزایا: شفاف، قابل حمل، آسان برای مسیر. معایب: تکثیر مستندات، تکامل ظریف دشوارتر است.

2. در هدر (مذاکره محتوا):

'پذیرش: درخواست/vnd. شرکت. پرداخت ها v2 + json '

مزایا: انعطاف پذیری, هیچ «زباله» در URL, تکامل مناسب از نوع رسانه. معایب: اشکال زدایی در مرورگر دشوارتر است، شما به یک مشتری منظم نیاز دارید.

3. در هدر سفارشی:

'X-API-نسخه: 2' (или 'API-نسخه: 2025-09-01')

مزایا: فقط در sluice. منفی: بدون استاندارد، مراقب باشید با کش.

4. نسخه مبتنی بر تاریخ:

خوب برای fintech/گزارش: قابل پیش بینی «کاهش» تغییر (به عنوان مثال سه ماهه)

5. منبع/مدل نسخه:

نقطه پایانی همان می تواند نمایش های مختلف را بازگرداند: "fields =..." یا "profile = lite" کامل ". این یک افزودنی است، نه جایگزینی برای نسخه.

توصیه: برای ادغام های خارجی - 'URI vN' + هدر رد/غروب آفتاب ؛ برای داخلی - شما می توانید 'Accept' یا هدر نسخه، اگر دروازه و پلت فرم از آن پشتیبانی می کند.

4) GraphQL

اولویت - بدون نسخه های جهانی. تکامل از طریق اضافه کردن زمینه ها/انواع و دفع ('مستهلک @ (دلیل:... "")').
شکستن تغییرات - فقط در پنجره های «بزرگ» (versioned schema namespace) با راهنمای مهاجرت.
به دنبال «n + 1» باشید و معنی فیلدهای موجود را تغییر ندهید.

5) gRPC/Protobuf

اعداد ثابت هستند. نشاندار کردن حوزههای حذف شده به عنوان «رزرو شده».
اضافه کردن فیلدها به عنوان اختیاری با پیش فرض امن.
برای بررسی سازگاری خودکار از buf breaking/lint استفاده کنید.
بسته ها/ماژول های نسخه: "پرداخت بسته. v1 ؛ → 'پرداخت. V2 '.

6) API های رویداد (EDA)

برنامه همان قرارداد است. آن را در رجیستری Schema (Avro/JSON-Schema/Protobuf) ذخیره کنید.
موضوعات و نسخهها: "پرداختها. V1 پرداخت های مجاز '،'. V2. مجاز است ".
شکستن تغییرات - یک نوع جدید از رویداد یا یک موضوع جدید.
تضمین تکامل: سازگار با عقب برای مصرف کنندگان در طول دوره LTS.

7) سیاست اداره و EOL

• استهلاک: برچسب ها در تغییرات و مشخصات (OpenAPI/GraphQL SDL)، هدر
• 'افسردگی: درست' و در صورت امکان 'غروب خورشید: تو، 31 مارس 2026 00:00:00 GMT'.
• ارتباطات: ایمیل/پورتال شریک، اطلاعیه های وب، یادداشت های انتشار.
• شرایط: MINOR - 3-6 ماه پشتیبانی، MAJOR - 9-18 ماه (بسته به بحرانی).
• پنجره های زمان: رفع در «API نسخه سیاست».

8) مسیریابی و انتشار

Gateway API (Kong/Apigee/Nginx/Envoy): قوانین با پیشوند «/v1/»، توسط هدر یا mediatype.

if ($http_accept ~ "vnd. company. payments. v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: نسخه جدید را در ۱-۵٪ از ترافیک رول کنید، معیارها و سیاهههای مربوط به خطاهای قرارداد را مقایسه کنید.
پرچم های ویژگی: پنهان کردن رفتار بدون تغییر قرارداد.
مهاجرت صفر خرابی: با MAJOR، ارائه دو نوشتن/خواندن از طرح داده ها.

9) تست قرارداد و کنترل سازگاری

OpenAPI Diff (یا swagger-diff) - بررسی کنید که MINOR/PATCH طرحوارهها را نشکند.
پوشش طیفی - سبک، ابرداده مورد نیاز (نسخه، استهلاک).
قراردادهای مبتنی بر مصرف کننده (پیمان) - تضمین می کند که ارائه دهنده مشتریان را شکستن نیست.
بوف شکستن для protobuf.
CI باید در شکستن تغییرات بدون افزایش MAJOR سقوط کند.

10) مستندات و SDK

نسخه مشخصات: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
تولید SDK توسط نسخه (npm/maven/pypi) با SemVer و changelog.
علامت گذاری روش های منسوخ در SDK با حاشیه نویسی/Deprecated.

11) مشاهده توسط نسخه

• RPS/latency/errors per version (برچسب «api _ version»).
• نقشه استفاده از نقطه پایانی: چه کس دیگری در v1 است ؟
• هشدارها: «> 10٪ 4xx به دلیل عدم تطابق قرارداد»، «مشتریان قدیمی> X٪ پس از تاریخ T».

12) ذخیره سازی و نسخه ها

نسخه ترانزیت قابلیت اتصال CDN را بهبود می بخشد.

• 'Vary: Accept, X-API-Version'.
• معانی پاسخ در MINOR را برای شکستن کلیدهای حافظه پنهان تغییر ندهید.

13) ایمنی

نسخه را در JWT رمزگذاری یا بخیه نکنید - نسخه توسط درخواست تعیین می شود، نه توکن.
شماره مجمع داخلی را فاش نکنید. از «v1/v2» برای پیام های خارجی استفاده کنید.
در MAJOR، اعتبار سنجی بررسی، محدودیت ها، ماسک PII.

14) مهاجرت و خودکار یاران

انتشار «راهنمای مهاجرت v1 → v2»: جدول نقشه برداری درست, درخواست نمونه/پاسخ, موارد لبه.
ما خطوط را برای مشتریان (CLI) ارائه می دهیم که زمینه های قدیمی را برجسته می کند.
برای شرکای بزرگ - sandbox با دو نسخه و یک مجموعه داده تست.

15) ضد الگوهای

«ابدی v1»: عدم مهلت و معیارهای استفاده.
پنهان تغییرات شکستن در MINOR/PATCH.
«نسخه در رشته پرس و جو» ('? v = 2 ') - حافظه پنهان و قابلیت خواندن را خراب می کند.
«One endpoint is hundred flag values»: دشوار برای تست/سند.

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

1. مدل انتخاب شده (URI/Accept/Header) برای مشتریان خارجی و داخلی.
2. SemVer برای مشخصات و SDK، خودکار شکستن چک در CI.
3. استهلاک/سیاست غروب آفتاب و قالب های ارتباطی.
4. مسیریابی دروازه + قناری، داشبورد بر اساس نسخه.
5. آزمایشات CDC/قرارداد برای یکپارچگی بحرانی (پرداخت، KYC، گزارش).
6. مستندات/SDK/راهنمای مهاجرت همزمان با انتشار منتشر می شود.
7. برنامه EOL با تاریخ و مسئول.

17) مثال ها

17. 1 استراحت (هدر URI +)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100. 00", "currency": "EUR"},
"limits": {"daily": "500. 00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 مذاکره محتوا

GET /payments/987
Accept: application/vnd. company. payments. v2+json
Vary: Accept

17. 3 GraphQL (بخش زمینه)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments. v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 مدل رویداد

• تمام شد. V1 تعادل. به روز شده
• تمام شد. V2. تعادل. تغییر (رویداد جدید با طرح گسترده)

طرح ها در رجیستری ذخیره می شوند، تولید کننده رویدادها را با یک طرح که سازگاری را نقض می کند منتشر نمی کند.

18) زمینه iGaming/fintech (تمرین)

پرداخت: ورودی v2 برای PSP های جدید که در آن «وضعیت »/« کاهش _ دلیل» تمدید شده است ؛ در دروازه، نقشه برداری v1 → v2 برای گزارش.
KYC: MINOR فیلد «pep _ screening» را اضافه می کند، مشتریان v1 را نادیده می گیرند، v2 - نیاز دارد.
بازی های مسئول/محدودیت: عمده تغییر مدل محدودیت (روزانه/هفتگی). صادرات دو برابر به گزارش قبل از EOL v1.
گزارش به تنظیم کننده ها: نسخه های ثابت - تاریخ: 'reporting-2025-01'.

19) مینی سیاست (به عنوان مثال برای ویکی)

مدل: برای API های خارجی - 'URI/vN/' ؛ برای داخلی - "قبول:... vN + json 'or' X-API-Version: N '.

SemVer: مشخصات و SDK ها به عنوان «N» منتشر می شوند. کوچک است. پچ. نیاز به RFC/ADR

سازگاری: MINOR/PATCH - بدون تغییر شکستن. شکستن فقط از طریق MAJOR.
تخفیف/EOL: اعلام ≥90 روزه ؛ تاریخ غروب آفتاب در عناوین ؛ شعبه LTS برای مشتریان بحرانی.
کنترل: OpenAPI diff/buf شکستن در CI، CDC برای ادغام کلید.
قابلیت مشاهده: معیارها/سیاهههای مربوط با برچسب 'api _ version'.
انتشار: قناری 5٪ ≥ 24 ساعت، سپس در مراحل تا 100٪ با معیارهای سبز.

مجموع

Versioning در مورد «/v2 در URL «نیست، بلکه در مورد روند است: قوانین صریح تکامل، چک های سازگاری خودکار، نسخه های مدیریت شده و احترام به ادغام. یک سیاست روشن، نظارت و مشاهده خودکار را وارد کنید - و تغییرات دیگر تهدیدی برای محصول نخواهد بود.