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

فاحص تسمية نقاط نهاية REST

الصق مسارًا مثل /users/{id}/orders لترى قواعد التسمية التي يحققها: أحرف صغيرة، وكلمات تفصلها واصلات، وأسماء بصيغة الجمع، ولا أفعال. تُذكر كل قاعدة مخالفة لكل مقطع، فيتحول تعليق المراجعة إلى إصلاح. مجاني في متصفحك.

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

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

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

مثال محلول

إذا أدخلت

المسار: /v1/users/{id}/orders

تحصل على

القطع: 4

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

كيف يبدو المسار جيد التسمية

الاصطلاح المقبول على نطاق واسع هو أن يكون كل مقطع من المسار اسمًا، وأن تستخدم المجموعات صيغة الجمع: ‎/users للمجموعة، و‎/users/{id} لعضو واحد فيها. تُفصل الكلمات داخل المقطع بواصلات، أي بأسلوب kebab-case، لأن الشرطات السفلية أصعب قراءةً في عناوين URL وقد تختفي تحت خطوط الروابط، بينما يخلط camelCase حالة الأحرف في موضع تُعد فيه الأحرف الصغيرة هي القاعدة. بادئات الإصدار مثل v1 أو v2 ممارسة مقبولة ولا تُعامل كأخطاء تسمية.

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

ما الذي تختبره هذه الأداة وكيف تقرر

تقسّم الأداة المسار عند الشرطات المائلة وتتجاهل سلسلة الاستعلام والمقطع المرجعي، لأنهما ليسا جزءًا من تسمية الموارد. ثم يُختبر كل مقطع متبقٍّ وفق أربع قواعد، ويُبلَّغ عن كل إخفاق على حدة كي ترى بالضبط أي اصطلاح خالفه المقطع. أولًا، الأحرف الصغيرة: يُعلَّم أي حرف كبير في المقطع، لأن حالة الأحرف في المسارات سبب شائع لأخطاء التوجيه على الخوادم الحساسة لحالة الأحرف.

ثانيًا، الوصل: تُعلَّم الشرطات السفلية والمسافات داخل المقطع، مع اعتماد الواصلات بديلًا. ثالثًا، أسماء الجمع: يُتوقع أن تنتهي المقاطع التي ليست بادئات إصدار ولا معاملات مسار بكلمة تبدو جمعًا؛ فيُعلَّم مقطع مثل ‎/user بينما ينجح ‎/users، وتُحكم المقاطع المركبة مثل ‎/user-profiles بكلمتها الأخيرة. رابعًا، الأفعال: تُقارن كل كلمة مفصولة بواصلات بقائمة ثابتة من الأفعال الإنجليزية الشائعة مثل get وcreate وupdate وdelete وfetch وlogin، ويُعلَّم أي تطابق.

معاملات المسار بصيغة {id} أو :id معفاة من قاعدتي الاسم والفعل، لأن اسم المعامل يتبع اصطلاحات مختلفة عن اسم المورد الثابت.

حالات الاستخدام

احجب المسارات الجديدة في CI

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

احسم خلافات الأسلوب في مراجعة التصميم

استبدل الرأي الشخصي بقائمة ملموسة من المخالفات عندما يختلف مراجعان حول صياغة المسار.

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

كم التكلفة؟

كما يمكن تشغيلها مجانًا في متصفحك على هذه الصفحة.

كيف تقرر الأداة ما إذا كانت الكلمة جمعًا؟

بأسلوب استقرائي بسيط وحتمي: يجب أن تنتهي آخر كلمة مفصولة بواصلات في المقطع بحرف 's'. مقاطع الإصدار مثل v1 ومعاملات المسار مثل {id} أو :id معفاة.

هل تفحص سلاسل الاستعلام أو المقاطع المرجعية؟

لا. كل ما بعد '?' أو '#' يُزال قبل الفحوص، لأن معاملات الاستعلام والمقاطع المرجعية ليست جزءًا من تسمية الموارد.

لماذا الواصلات بدل الشرطة السفلية أو camelCase؟

الشرطة السفلية أصعب قراءة في عنوان الويب وقد تختفي تحت خط الرابط، بينما يخلط camelCase الأحرف الكبيرة في مكان تكون فيه الأحرف الصغيرة هي القاعدة. لذلك تُعلَّم الشرطات السفلية والمسافات وتُقترح الواصلة بديلًا.

هل تُعد بادئات الإصدار مثل v1 خطأ؟

لا. بادئات الإصدار مثل v1 أو v2 ممارسة مقبولة، فلا تُعامل على أنها أخطاء في التسمية، ولا يُشترط أن تكون أسماء بصيغة الجمع.

أدوات ذات صلة

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

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

الـEndpoint

POSThttps://api.kit.forhosting.com/dev/rest-endpoint-naming-check

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

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

curl -X POST https://api.kit.forhosting.com/dev/rest-endpoint-naming-check \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/api/v1/user-profiles"}'

const res = await fetch("https://api.kit.forhosting.com/dev/rest-endpoint-naming-check", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "path": "/api/v1/user-profiles"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev/rest-endpoint-naming-check",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "path": "/api/v1/user-profiles"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/rest-endpoint-naming-check", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"path":"/api/v1/user-profiles"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"path":"/api/v1/user-profiles"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/rest-endpoint-naming-check", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

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

{
  "path": "/api/v1/user-profiles"
}

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

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

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

الأسعار

لكل طلب$0.002

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

الحدود

max_chars 2048

الأخطاء

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

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

تأخذ أداة فحص تسمية نقاط نهاية REST مسارًا مثل /users/{id}/orders وتختبر كل مقطع منه وفق الاصطلاحات التي تتفق عليها معظم أدلة الأسلوب: يجب أن تكون المقاطع بأحرف صغيرة، وأن تُفصل الكلمات بواصلات لا بشرطات سفلية أو camelCase، وأن تكون موارد المجموعات أسماء جمع، وأن تبقى الأفعال خارج المسار لأن أسلوب HTTP يسمّي الإجراء أصلًا.

كيف يبدو مسار REST الجيد

مسارات REST تسمّي الموارد لا الإجراءات. الإجراء موجود أصلًا في أسلوب HTTP — GET، POST، PUT، DELETE — لذا فإن مسارًا مثل /getUsers يقول الشيء نفسه مرتين وبطريقة لا تتسق مع بقية API.

استخدام الحكم في المراجعات وخطوط الأتمتة

صُمم الناتج ليكون قابلًا للاستهلاك الآلي وكذلك مقروءًا. سير العمل النموذجي هو تشغيل الأداة على كل مسار جديد تضيفه الخدمة: ألصق المسار أثناء مراجعة التصميم، والتقط الانحراف قبل أن يصدر المسار، وتجنّب لاحقًا الاختيار المؤلم بين إبقاء مسار قبيح إلى الأبد أو كسر العملاء بإعادة تسمية. فإلى جانب قائمة المشكلات بلغة واضحة تحصل على كائن checks يضم قيمة منطقية لكل اصطلاح — lowercase وhyphenated وplural_nouns وno_verbs — إضافة إلى علامة valid الإجمالية، فيستطيع مهمة CI أن ترفض طلب دمج بناءً على شرط واحد بدل تحليل جمل نصية. تستخدمها الفرق أيضًا أثناء تدقيق واجهات API، بتمرير المسارات من مستند OpenAPI وجمع المقاطع التي تحتاج انتباهًا. الشيفرة نفسها التي تشغّل API تعمل مجانًا في متصفحك على هذه الصفحة، فيمكنك اختبار المسارات تفاعليًا أثناء التصميم ولا تدفع $0.002 عن كل طلب إلا عندما تؤتمت الفحص داخل خط أتمتة أو أداة فحص أو بوابة مطورين داخلية.

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

دقّق واجهة API قائمة

مرّر المسارات من مستند OpenAPI عبر الأداة واجمع المقاطع التي تخالف دليل أسلوبك.

أسئلة تقنية

لماذا لا تُسمح الأفعال في مسار REST؟

لأن أسلوب HTTP يسمّي الإجراء أصلًا. مسار مثل ‎/getUsers يكرر GET وينحرف عن اتساق بقية API؛ بينما ‎/users مع أسلوب GET يقول الشيء نفسه باتساق.

ماذا يحدث إذا أرسلت مسارًا فارغًا؟

يفشل الطلب بخطأ invalid_input يوضح أن المسار غير الفارغ مطلوب. المدخل الفارغ لا يُحتسب أبدًا.

ما قائمة الأفعال التي تستخدمها؟

قائمة ثابتة من الأفعال الإنجليزية الشائعة المرئية في واجهات API حقيقية — get وcreate وupdate وdelete وfetch وfind وsearch وadd وremove وlogin وregister وما شابه. القائمة حتمية ولا تتغير بين الاستدعاءات.

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

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