ForHosting KIT · قراءة المواقع ومراقبتها

اكتشف مخطط إصدارات API من عنوان URL

العنوان الذي يبدأ مساره بالمقطع v1 يستخدم الإصدار القائم على المسار، والإصدار 1، وموضعه /v1. الصق أي عنوان لتعرف هل الإصدار في المسار أم بعد علامة الاستفهام أم في الترويسات فقط، وهذا مفيد للبوابات والتوثيق. مجاني في متصفحك.

مجاني
يعمل في متصفحك
دون تسجيل
بياناتك لا تغادر جهازك

شغّل الأداة مجانًا اطّلع على الـAPI

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

مثال محلول

إذا أدخلت

عنوان الويب: https://api.example.com/v1/users

تحصل على

المخطط: path_based
الإصدار: 1
الإصدار الخام: v1
الموقع: /v1

عندما يظهر الإصدار في المسار أو الاستعلام يُستخرج ويُعاد مع الرمز الخام والموقع الذي طابق.

ثلاثة أماكن تضع فيها خدمة الويب إصدارها

تعلن خدمات الويب عن إصدارها بطرق مختلفة. أشيعها مقطع في المسار مثل v2 بين شرطتين مائلتين داخل العنوان نفسه. والطريقة الثانية مفتاح بعد علامة الاستفهام يحمل الرقم، كإصدار قيمته 2. أما الثالثة فتترك العنوان خاليًا وتنتظر أن يصل الإصدار منفصلًا في الترويسات. الصق عنوانًا كاملًا فيخبرك الكاشف بالأسلوب المستخدم، وإذا كان الإصدار ظاهرًا فبقيمته وموضعه. فالعنوان الذي يبدأ مساره بالمقطع v1 ثم users يُصنَّف إصدارًا قائمًا على المسار، رقمه 1، ونصه الأصلي v1، وموضعه /v1.

ما الذي يتحقق منه الكاشف وما الذي لا يفعله أبدًا

لا تُقبل إلا العناوين الكاملة التي تبدأ بالبادئة http أو https، ويُرفض غيرها بدل تخمينه. وتُقارن المفاتيح بعد علامة الاستفهام دون تمييز بين الأحرف الكبيرة والصغيرة، ويفوز أول مفتاح له قيمة في قائمة أولويات ثابتة، فلا يغيّر ترتيب العناصر الإجابة. ويُختصر الإصدار المكتوب v2 إلى 2، بينما يبقى 1.0.0 كما هو، وتبقى كلمات مثل beta وتواريخ مثل 2024-01-01 دون تغيير. ولا يتصل الكاشف بالخدمة ولا يخترع إصدارًا من اسم المضيف، لذا يعطي العنوان نفسه الإجابة نفسها دائمًا.

كيف تُميَّز مخططات المسار والاستعلام والترويسة الضمنية

ويتعرف أيضًا على الشكل ذي المقطعين version/1 أو versions/2.0 حتى تُصنَّف مسارات أسلوب التوثيق بشكل صحيح. تُطابق المفاتيح بلا حساسية لحالة الأحرف؛ ويفوز أول مفتاح في قائمة الأولوية الثابتة بقيمة غير فارغة، فتبقى النتائج مستقرة مهما كان ترتيب المعاملات في عنوان URL الأصلي. قد تبدو القيم 2 أو v2 أو 1.0.0؛ وتُزال v البادئة من حقل version المُطبَّع عندما يكون الرمز رقميًا بحتًا مع نقاط اختيارية.

تُحفظ الرموز الأبجدية الرقمية الحرة مثل beta أو 2024-01-01 كما هي إن طابقت نمط معرّف آمن. لا ينفّذ الكاشف أي إدخال/إخراج شبكي ولا يخترع إصدارًا من أسماء المضيفين وحدها.

الأسئلة الشائعة

ما الذي يُعد إصدارًا قائمًا على المسار؟

مقطع مسار يطابق v متبوعة بإصدار رقمي (v1، v2.0) أو الشكل version/1 أو versions/2.0.

ماذا يعني عدم العثور على إصدار في العنوان؟

يعني أن النتيجة هي الإصدار عبر الترويسات: فلا المسار ولا الجزء الذي بعد علامة الاستفهام يحمل علامة إصدار. وعادةً تنتظر هذه الخدمات الإصدار في الترويسات، أو لا تضعه في العنوان أصلًا.

هل يهم ترتيب العناصر بعد علامة الاستفهام؟

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

ماذا يحدث للإصدارات المكتوبة مثل v2 أو 1.0.0؟

يُحذف حرف v في البداية إذا كان الباقي أرقامًا ونقاطًا فقط، فيصبح v2 هو 2 ويبقى 1.0.0 كما هو. أما كلمات مثل beta أو تاريخ مثل 2024-01-01 فتبقى دون تغيير.

هل تزور الأداة العنوان الذي ألصقه؟

لا. فهي تقرأ نص العنوان فقط ولا تتصل بالخدمة أبدًا، ولا تستنتج إصدارًا من اسم المضيف وحده، لذلك يُعرض العنوان الخالي من العلامة على حقيقته.

أدوات ذات صلة

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/dev/api-versioning-scheme-detect

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/dev/api-versioning-scheme-detect \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/v1/users"}'

const res = await fetch("https://api.kit.forhosting.com/dev/api-versioning-scheme-detect", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://api.example.com/v1/users"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev/api-versioning-scheme-detect",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "url": "https://api.example.com/v1/users"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/api-versioning-scheme-detect", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"url":"https://api.example.com/v1/users"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"url":"https://api.example.com/v1/users"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/api-versioning-scheme-detect", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "url": "https://api.example.com/v1/users"
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "dev.api_versioning_scheme_detect",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

ملاحظات تقنية

تعلن واجهات HTTP العامة عن أسلوب الإصدارات في مواضع مختلفة: مقطع مسار مثل /v2/، أو سلسلة استعلام مثل ? api_version=2، أو لا شيء في عنوان URL عندما يُتوقع من العملاء إرسال Accept أو ترويسات مخصصة. تحتاج التكاملات والبوابات ومولّدات SDK وزواحف التوثيق إلى إجابة حتمية واحدة عن المخطط الذي يستخدمه عنوان نقطة النهاية وعن رمز الإصدار الذي يحمله. تقبل هذه القدرة عنوان API مطلقًا واحدًا، وترفض السلاسل التي ليست عناوين http أو https سليمة التكوين، وتصنف المخطط إلى path_based أو query_param أو header_implied. وإذا لم يحتوِ المسار ولا الاستعلام على علامة إصدار تقليدية تكون النتيجة header_implied مع has_version false، بما يشير إلى أن الإصدارات تُنقل خارج النطاق بالنسبة إلى عنوان URL. تغذي وحدة التحليل النقي ذاتها الأداة المجانية في المتصفح ومسار API المدفوع مسبقًا، فلا تختلف عمليات التدقيق وفحوص CI وخطوط الإنتاج حول حالة حدّية في التصنيف.

كيف تُميَّز مخططات المسار والاستعلام والترويسة الضمنية

الإصدارات القائمة على المسار هي عرف REST السائد: يظهر مقطع مثل v1 أو v2 أو v1.2.3 في pathname، غالبًا تحت /api/ أو كأول مقطع ذي معنى بعد المضيف. يمشي هذا الكاشف مقاطع المسار من اليسار إلى اليمين ويعامل مطابقة غير حساسة لحالة الأحرف لـ v متبوعة بإصدار رقمي على أنها path_based، فيعيد الجزء الرقمي كـ version والمقطع الأصلي كـ version_raw مع location مضبوط على ذلك المقطع (مثل /v2). تضع إصدارات معلمة الاستعلام الرمز في سلسلة البحث تحت مفاتيح شائعة منها version وapi_version وapi-version وapiversion وver وv. عندما يطابق المسار والاستعلام معًا تكون الأولوية لـ path_based لأن توثيق REST العام يعامل مقطع المسار كعقد أساسي وسلسلة الاستعلام كتجاوز ثانوي في أغلب الأحيان. وإذا لم يُنتج أي مصدر إصدارًا يكون المخطط header_implied: عنوان URL وحده لا يرمّز إصدارًا، وهذا في واجهات حديثة يعني غالبًا Accept: application/vnd.example.v1+json أو ترويسة X-API-Version مخصصة أو سطحًا بلا إصدار.

عقد الإدخال وحمولة النجاح وأخطاء التحقق

مثال: https://api.example.com/users? أرسل جسم JSON بطريقة POST يحوي حقل سلسلة واحدًا مطلوبًا اسمه url. يجب أن تكون القيمة عنوانًا مطلقًا سليم التكوين بمخطط http أو https؛ تفشل المسارات النسبية وأسماء المضيف بلا مخطط والسلاسل الفارغة والأنواع غير النصية والبروتوكولات الأخرى مثل ftp أو mailto بـ invalid_input ولا تُحاسب. عند النجاح تتضمن الاستجابة دائمًا url المُعاد، وscheme (أحد path_based أو query_param أو header_implied)، وhas_version (منطقي)، وpath (pathname)، وhost. عندما يكون has_version صحيحًا تتضمن الحمولة أيضًا version (رمزًا مُطبَّعًا) وversion_raw (كما وُجد في URL) وlocation (مؤشرًا قصيرًا مثل /v2 أو ? api_version=2). في نتائج query_param يسجّل param_name إملاء المفتاح الأصلي من URL. تُحذف الحقول الاختيارية بدل ضبطها على null عندما يكون has_version خاطئًا، فيبقى العقد آمنًا للـ DOM وسهل العرض. مثال: https://api.example.com/v2/users يعطي scheme path_based وversion 2 وlocation /v2. api_version=2 يعطي scheme query_param وversion 2 وparam_name api_version. مثال: https://api.example.com/users بلا علامات إصدار يعطي scheme header_implied وhas_version false. استخدم الأداة المجانية في المتصفح للفحص الفردي، أو واجهة API بسعر $0.002 لكل عنصر ناجح عند تصنيف نقاط النهاية بالجملة من ملف جرد أو زحف OpenAPI.

أين تُجدي فائدة اكتشاف إصدارات عنوان URL

تحصي فرق المنصة مئات عناوين الأساس الداخلية والشراكة وتحتاج وسمًا متسقًا قبل توجيه الحركة عبر بوابة تفرض نوافذ الإيقاف التدريجي. التحقق الفاشل لا يستهلك الرصيد. تفرّع مولّدات SDK وأدوات تهيئة العملاء القوالب بحسب ما إذا كان الخادم يتوقع /vN/ في المسار أو علم استعلام أو إصدارات بالترويسات فقط؛ ويغني المصنّف النقي عن تعبيرات منتظمة هشة مبعثرة عبر المستودعات. تعرض مواقع التوثيق وأسواق API شارات أسلوب الإصدارات بجانب كل قائمة؛ وتغذيتها بهذه النقطة تبقي نص التسويق متوافقًا مع شكل URL الحي. كثيرًا ما تسأل مراجعات الأمن والامتثال عما إذا كانت مضيفات الإنتاج ما زالت تكشف مسارات بلا إصدار أو مخططات مختلطة تعقّد طرح التغييرات الكاسرة؛ وتصدير scheme وhas_version إلى جدول يجيب عن ذلك في مرور واحد. يمكن لمهام CI أن ترفض طلب دمج عندما تتحول قاعدة خدمة مضافة حديثًا بصمت من path_based إلى header_implied بلا ADR. ولأن التنفيذ تحليل parse نقي من المستوى A، تكلف كل مكالمة ناجحة السعر الأساسي المنشور $0.002 بلا رموز نموذج وبلا جلب للمضيف الهدف.

حالات التكامل

جرد API وتوجيه البوابة

صنّف عناوين الأساس في كتالوج الخدمات كـ path_based أو query_param أو header_implied قبل تطبيق سياسات الإيقاف وقواعد التوجيه.

تهيئة SDK والعملاء

اختر قالب URL الصحيح عند توليد SDK: أدرج /vN/ أو أضف ?version= أو وثّق ترويسات Accept المطلوبة عندما لا يحمل العنوان إصدارًا.

شارات التوثيق ومراجعات الامتثال

وسّم قوائم API العامة بأسلوب الإصدارات وأشر إلى مضيفات الإنتاج بلا إصدار في مراجعات الأمن أو البنية.

أسئلة تقنية

كيف أكتشف مخطط إصدارات واجهة API من عنوان URL؟

أرسل عنوان http(s) مطلقًا سليم التكوين في الحقل url. يكون scheme الاستجابة path_based أو query_param أو header_implied، مع استخراج version عند وجوده في المسار أو سلسلة الاستعلام.

أي معلمات استعلام تُعرَف؟

version وapi_version وapi-version وapiversion وver وv، بلا حساسية لحالة الأحرف وبهذا ترتيب الأولوية. أول قيمة غير فارغة تنتج scheme query_param.

ماذا يعني header_implied؟

لا يحمل المسار ولا سلسلة الاستعلام علامة إصدار تقليدية. تُنقل الإصدارات عبر الترويسات (Accept، X-API-Version) أو تكون الواجهة بلا إصدار في URL.

كم يكلف اكتشاف مخطط إصدارات واجهة API؟

أداة المتصفح مجانية. تستخدم طلبات API رصيد KIT المدفوع مسبقًا بسعر $0.002 لكل مكالمة ناجحة؛ والعناوين غير الصالحة أو غير سليمة التكوين لا تُحاسب.

اطّلع على توثيق KIT الكامل ←

شغّل الأداة مجانًا

مثال محلول

ثلاثة أماكن تضع فيها خدمة الويب إصدارها

ما الذي يتحقق منه الكاشف وما الذي لا يفعله أبدًا

كيف تُميَّز مخططات المسار والاستعلام والترويسة الضمنية

الأسئلة الشائعة

أدوات ذات صلة

للمطوّرين — الوصول عبر API

الـEndpoint

استدعِ الخدمة من بيئتك

مثال على الطلب

مثال على الاستجابة

الأسعار

الأخطاء

ملاحظات تقنية

كيف تُميَّز مخططات المسار والاستعلام والترويسة الضمنية

عقد الإدخال وحمولة النجاح وأخطاء التحقق

أين تُجدي فائدة اكتشاف إصدارات عنوان URL

حالات التكامل

جرد API وتوجيه البوابة

تهيئة SDK والعملاء

شارات التوثيق ومراجعات الامتثال

أسئلة تقنية

شكرًا