التكنولوجيا والبنية التحتية → تحديث واجهة برمجة التطبيقات

إصدار API

1) لماذا تحتاجه

• يقلل من مخاطر الحوادث أثناء عمليات الإفراج،
• يسمح لك بجدولة التحسينات والسلامة،
• يعطي الشركات جداول زمنية يمكن التنبؤ بها لهجرات الشركاء.

2) تصنيف التغييرات

PATCH (عدم كسر): تصحيحات دون تغيير العقد (إضافة حقول اختيارية، إصلاحات التحقق).
MINOR: امتدادات متوافقة مع الظهر (نقاط نهاية جديدة، حقول مع افتراضي).
MAJOR (كسر): تغيير الهيكل أو الدلالات أو حذف الحقول/نقاط النهاية.

يوصى بـ SemVer 'MAJOR. قاصر. PATCH 'للقطع الأثرية (SDK/schemas)، بينما يمكن تبسيط رقم API «الخارجي» (v1، v2).

3) نماذج إصدار REST

1. إلى يوري:

'GET/v1/payments/{ id}'

الإيجابيات: شفافة، قابلة للتحويل، سهلة التوجيه. السلبيات: ازدواجية الوثائق، يصعب تطويرها بمهارة أكبر.

2. في العناوين (التفاوض على المحتوى):

'قبول: طلب/فند. الشركة. المدفوعات. v2 + json '

الإيجابيات: المرونة، عدم وجود «قمامة» في عنوان URL، تطور مناسب من نوع الوسائط. السلبيات: من الصعب التنقيح في المتصفح، فأنت بحاجة إلى عميل منضبط.

3. في الترويسة المخصصة:

«X-API-Version: 2» (или «Api-Version: 2025-09-01»)

الإيجابيات: فقط على السبيكة. السلبيات: لا توجد معايير، احذر مع ذاكرة التخزين المؤقت.

4. النسخة المستندة إلى التاريخ:

جيد للتكنولوجيا المالية/الإبلاغ: «تخفيضات» يمكن التنبؤ بها في التغيير (على سبيل المثال كل ثلاثة أشهر).

5. إحياء الموارد/النماذج:

التوصية: للتكامل الخارجي - 'URI vN' + الرفض/رؤوس الغروب ؛ للداخلي - يمكنك «قبول» أو رأس الإصدار، إذا دعمته البوابة والمنصة.

4) الرسم البياني QL

التفضيل - لا توجد إصدارات عالمية. التطور من خلال إضافة الحقول/الأنواع والاكتئاب ('@ disprecated (السبب:... "")').
كسر التغييرات - فقط في النوافذ «الكبيرة» (مساحة اسم المخطط) مع دليل الهجرة.
راقب «n + 1» ولا تغير معنى الحقول الموجودة.

5) gRPC/Protobuf

الأرقام الميدانية غير قابلة للتغيير. ضع علامة على الحقول المحذوفة على أنها «محفوظة».
أضف الحقول على أنها اختيارية مع افتراضي آمن.
استخدم buf breaking/lint لفحص التوافق التلقائي.
حزم/وحدات الإصدار: 'مدفوعات الطرود. v1 ؛ مدفوعات '→'. v2 '.

6) واجهات برمجة التطبيقات (EDA)

مخطط الحدث هو نفس العقد. قم بتخزينه في سجل المخطط (Avro/JSON-Schema/Protobuf).
المواضيع والنسخ: المدفوعات. v1. المدفوعات المأذون بها. v2. مأذون به '.
كسر التغييرات - نوع جديد من الأحداث أو موضوع جديد.
ضمانات التطور: متوافقة مع التخلف للمستهلكين خلال فترة LTS.

7) سياسة الإزالة و EOL

• الاستنكار: الملصقات بلغة التغيير والمواصفات (OpenAPI/GraphQL SDL)، الرأس
• «الاكتئاب: صحيح» وعندما يكون ذلك ممكنًا «غروب الشمس: الثلاثاء، 31 مارس 2026 00:00:00 بتوقيت جرينتش».
• الاتصالات: البريد الإلكتروني/بوابة الشريك، إشعارات خطوط الويب، ملاحظات الإصدار.
• المصطلحات: MINOR - 3-6 أشهر من الدعم، MAJOR - 9-18 شهرًا (حسب الأهمية).
• نوافذ الوقت: إصلاح في «API Veronizing Policy».

8) التوجيه والإطلاقات

بوابة API (Kong/Apigee/Nginx/Envoy): القواعد حسب البادئة '/v1/'، بالرأس أو الوسيط.

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

Canary/Blue-Green/Shadow: قم بتدوير الإصدار الجديد على 1-5٪ من حركة المرور، وقارن المقاييس وسجلات أخطاء العقد.
أعلام الميزة: إخفاء السلوك دون تغيير العقد.
الهجرة بدون توقف: مع MAJOR، توفير الكتابة المزدوجة/قراءة مخطط البيانات.

9) اختبار العقود ومراقبة التوافق

OpenAPI Diff (أو swagger-diff) - تحقق من أن MINOR/PATCH لا يكسر المخططات.
Spectral linting - style, required metadata (version, Deprecation).
العقود التي يحركها المستهلك (ميثاق) - تضمن أن المزود لا يكسر العملاء.
buf breaking для protobuf.
يجب أن يقع CI في كسر التغييرات دون إثارة MAJOR.

10) التوثيق و SDK

الإصدار المواصفات: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
قم بتوليد SDK حسب الإصدار (npm/maven/pypi) باستخدام SemVer و changelog.
وضع علامة على الأساليب المهجورة في SDK مع/شروح مستنكرة.

11) الملاحظة حسب النسخة

• RPS/latency/خطأ لكل إصدار (علامة 'api _ version').
• خرائط استخدام نقطة النهاية: من أيضًا في v1 ؟
• التنبيهات: «> 10٪ 4xx بسبب عدم تطابق العقد»، «العملاء القدامى> X٪ بعد T-date».

12) التخزين المؤقت والنسخ

يحسن الإصدار أثناء العبور قابلية CDN للتخزين المؤقت.

• «Vary: Accept، X-API-Version».
• لا تغير دلالات الاستجابة في MINOR لكسر مفاتيح ذاكرة التخزين المؤقت.

13) السلامة

لا تقوم بتشفير أو خياطة الإصدار في JWT - يتم تحديد الإصدار من خلال الطلب، وليس الرمز.
لا تكشف عن أرقام التجميع الداخلية. استخدم «v1/v2» للرسائل الخارجية.
في MAJOR، مراجعة التحقق، الحدود، قناع PII.

14) الهجرات والمساعدة الذاتية

نشر «دليل الهجرة v1 → v2»: جدول رسم الخرائط الميدانية، عينة من الطلبات/الردود، حالات الحافة.
نحن نقدم بطانات للعملاء (CLI) تسلط الضوء على المجالات القديمة.
للشركاء الكبار - صندوق الرمل بنسختين ومجموعة بيانات اختبار.

15) الأنماط المضادة

«Eternal v1»: عدم وجود مواعيد نهائية ومقاييس استخدام.
تغييرات كسر مخفية في MINOR/PATCH.
«نسخة في سلسلة الاستعلام» (؟ v = 2 ') - كسر ذاكرة التخزين المؤقت وقابلية القراءة.
«نقطة النهاية الواحدة هي مائة قيمة علم»: يصعب اختبارها/توثيقها.

16) قائمة التنفيذ المرجعية

1. نموذج مختار (URI/Accept/Header) للعملاء الخارجيين والداخليين.
2. SemVer للمواصفات و SDK، فحص الكسر التلقائي في CI.
3. سياسة الاستنكار/غروب الشمس ونماذج الاتصال.
4. توجيه البوابة + جزر الكناري، لوحات القيادة حسب الإصدار.
5. اختبارات CDC/العقد للتكامل الحرج (المدفوعات، KYC، الإبلاغ).
6. وينشر دليل الوثائق/SDK/الهجرة في نفس الوقت الذي يصدر فيه.
7. خطة EOL مع التواريخ والمسؤولية.

17) أمثلة

17. 1 REST (URI + Headers)

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 (Field Depriction)

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 نموذج الحدث

• 'wallet. v1. التوازن. تم تحديثها "
• 'wallet. v2. التوازن. تغير '(حدث جديد مع مخطط موسع)

يتم تخزين المخططات في قلم المحكمة، ولا ينشر المنتج الأحداث مع مخطط ينتهك التوافق.

18) سياق iGaming/fintech (ممارسة)

المدفوعات: المدخلات v2 لشركات القطاع الخاص الجديدة حيث يتم تمديد 'الحالة '/' الانخفاض _ السبب' ؛ على البوابة، رسم خرائط v1 → v2 للإبلاغ.
KYC: يضيف MINOR المجال «pep _ screening»، ويتجاهل العملاء v1، v2 - المطلوب.
الألعاب/الحدود المسؤولة: يغير MAJOR نموذج الحدود (يوميًا/أسبوعيًا). تصدير مزدوج للإبلاغ قبل EOL v1.
تقديم التقارير إلى المنظمين: الإصدارات - التواريخ الثابتة: «الإبلاغ - 2025-01».

19) سياسة مصغرة (مثال على ويكي)

النموذج: لواجهات برمجة التطبيقات الخارجية - 'URI/vN/' ؛ للداخلية - 'قبول:... vN + json 'أو' X-API-Version: N '.
SemVer: يتم نشر المواصفات و SDKs باسم 'N. قاصر. التصحيح '. يتطلب MAJOR RFC/ADR.
التوافق: MINOR/PATCH - لا توجد تغييرات كسر. كسر → فقط من خلال الرائد.
الاستنكار/EOL: إعلان لمدة ≥90 أيام ؛ تاريخ غروب الشمس في العناوين الرئيسية ؛ فرع LTS للعملاء المهمين.
التحكم: OpenAPI diff/buf breaking في CI، CDC للتكامل الرئيسي.
إمكانية الرصد: مقاييس/سجلات تحمل بطاقة «api _ version».
الإصدارات: كناري 5٪ ≥ 24 ساعة، ثم على مراحل إلى 100٪ بمقاييس خضراء.

النتيجة

لا يتعلق الإصدار بـ «/v2 في عنوان URL «، ولكن يتعلق بالعملية: قواعد صريحة للتطور، وفحص التوافق التلقائي، والإصدارات المدارة واحترام عمليات التكامل. أدخل سياسة واضحة، وأتمتة المراقبة والمراقبة - ولن تشكل التغييرات تهديدًا للمنتج.