اقتراح فعل HTTP لإجراءات CRUD في REST
اكتب create لتحصل على الطريقة المعتادة مع 201 Created وتلميح للمسار وملاحظة عن العرف المتبع، أما update فتعيد PUT للاستبدال الكامل وتشير إلى PATCH للتغييرات الجزئية. الإجراء نفسه يعطي الجواب نفسه دائمًا. مجاني في متصفحك.
- مجاني
- يعمل في متصفحك
- دون تسجيل
- بياناتك لا تغادر جهازك
شغّل الأداة مجانًا
مثال محلول
- الإجراء
- create
- الحالة
- 201
- نص الحالة
- Created
- تلميح المسار
- POST /resources
إنه ربط حتمي وليس تخمينًا: الإجراء نفسه يعيد الإجابة نفسها دائمًا دون أي نموذج. وتُرفض الإجراءات غير المعروفة بخطأ واضح يسرد القيم المقبولة، فيفشل أي خطأ إملائي في الأتمتة بصوت مسموع بدل أن ينتج مسارًا خاطئًا في صمت.
لماذا PUT للتحديث، وأين يقع PATCH
أكثر خلايا الجدول جدلًا هي خلية التحديث. أما PATCH فقد وُجد للحالة الشائعة الأخرى، حين يرسل العميل الحقول المتغيرة فقط ويقوم الخادم بدمجها؛ وتشير الملاحظة المُعادة إلى ذلك صراحةً، فيرى المراجع البديل بدل أن يتعامل مع الربط بوصفه عقيدة. عمليًا تستخدم واجهات برمجية كثيرة PATCH للتحديثات الجزئية وتخص PUT للاستبدال الكامل، وبعضها يستغني عن PUT كليًا.
والأهم في أي تصميم هو اختيار اصطلاح واحد وتطبيقه باتساق على كل الموارد، وهو بالضبط نوع القرار الذي يساعد بحث حتمي على فرضه عندما يُدمج في أدوات التوليد وقوائم مراجعة الشيفرة.
رموز الحالة نصف الإجابة
اختيار الفعل ليس سوى نصف تصميم المسار؛ فرمز حالة النجاح هو النصف الآخر، والخطأ فيه يربك العملاء. فعملية إنشاء تعيد 200 OK بدلًا من 201 Created ليست معطوبة، لكنها تهدر إشارة توفرها المواصفة مجانًا، ويسيء فهمها العملاء الآليون الذين يتفرعون بناءً على الحالة. وعملية حذف تعيد 200 بجسم فارغ تجبر العميل على تحليل لا شيء، حيث كان 204 No Content سيقول كل شيء في سطر الحالة وحده.
الربط المعاد هنا يقرن كل إجراء بالحالة التي ينبغي أن ينتجها الاستدعاء الناجح — 201 للإنشاء، و200 للقراءة والتحديث والسرد، و204 للحذف — مع العبارة الوصفية القياسية، فتخرج التوثيقات المولدة وأقسام الاستجابات في OpenAPI صحيحة بالبناء. أما الأخطاء فهي خارج النطاق عمدًا: تجيب الأداة عن اصطلاح المسار الناجح فحسب، وترفض أسماء الإجراءات غير المعروفة برسالة واضحة تسرد القيم الخمس المقبولة بدل تخمين قيمة قريبة.
حالات الاستخدام
مراجعة تصميم واجهة برمجية
قارن قائمة المسارات المقترحة بالربط الاصطلاحي وعلّم على المسارات المنحرفة قبل نشرها.
الأسئلة الشائعة
ما التكلفة؟
ويعمل الربط نفسه مجانًا في متصفحك على هذه الصفحة.
ما الإجراءات المقبولة؟
إنشاء، قراءة، تحديث، حذف، سرد. المطابقة غير حساسة لحالة الأحرف وتُتجاهل المسافات المحيطة؛ ويُرفض أي شيء آخر بخطأ يسرد القيم المقبولة.
لماذا PUT وليس PATCH للتحديث؟
PUT هو الاستبدال الكامل الاصطلاحي المتساوي المفعول، وهو ما يعيده الربط. وتشير الملاحظة في الاستجابة إلى PATCH بوصفه الخيار القياسي للتحديثات الجزئية لتختار عن قصد.
هل يمكن أن تكون الإجابة عشوائية أو مولدة بنموذج؟
لا. الربط جدول حتمي ثابت؛ فالإجراء نفسه يعيد دائمًا الفعل والحالة والملاحظة ذاتها.
هل ينبغي أن يرد إجراء الإنشاء بالحالة 200 أم 201؟
بالحالة 201 Created، وعادةً مع ترويسة Location تشير إلى المورد الجديد. والرد 200 OK ليس خطأ، لكنه يهدر إشارة توفرها المواصفة أصلًا، وقد يسيء فهمه العميل الذي يتصرف بحسب الحالة.
أدوات ذات صلة
للمطوّرين — الوصول عبر API
كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.
الـEndpoint
صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.
استدعِ الخدمة من بيئتك
curl -X POST https://api.kit.forhosting.com/dev/http-method-from-action-suggest \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"create"}'const res = await fetch("https://api.kit.forhosting.com/dev/http-method-from-action-suggest", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"action": "create"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev/http-method-from-action-suggest",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"action": "create"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/http-method-from-action-suggest", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"action":"create"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"action":"create"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/http-method-from-action-suggest", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)مثال على الطلب
{
"action": "create"
}مثال على الاستجابة
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev.http_method_from_action_suggest",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.
الأسعار
السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.
الأخطاء
| HTTP | الرمز | المعنى |
|---|---|---|
401 | unauthorized | مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك. |
402 | insufficient_balance | رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة. |
404 | unknown_type | نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب. |
429 | rate_limited | تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة. |
ملاحظات تقنية
تجيب أداة تحديد فعل HTTP لإجراء CRUD عن السؤال الذي يطرحه كل مصمم واجهات برمجية عشرات المرات يوميًا: عندما يكون لديك إجراء مثل إنشاء أو قراءة أو تحديث أو حذف أو سرد، فما فعل HTTP الذي ينبغي أن يستخدمه المسار، وما رمز الحالة الذي يجب أن يعيده الاستدعاء الناجح؟ ترسل اسم إجراء واحدًا فتستلم الفعل الاصطلاحي في REST، ورمز النجاح المعتاد مع عبارته الوصفية، وتلميحًا لمسار يوضح كيفية كتابة المسار عادةً، وملاحظة قصيرة تشرح الاصطلاح. استخدمها عند توليد هياكل المسارات، أو مراجعة تصميم واجهة برمجية، أو إنشاء هياكل OpenAPI، أو تعليم اصطلاحات REST لفريق يخلط باستمرار بين PUT و PATCH.
الربط الاصطلاحي في جدول واحد
أما التحديث فيرتبط بـ PUT عندما يستبدل العميل المورد بالكامل، ويعيد 200 OK مع التمثيل المحدّث؛ والمسار نفسه متساوي المفعول، فإعادة إرسال الطلب لا تُحدث ضررًا إضافيًا. والحذف يرتبط بـ DELETE ويعيد عادةً 204 No Content، إذ لم يبقَ شيء يُوصف. تعيد هذه الأداة ذلك الصف من الجدول بالضبط مع تبريره مرفقًا، فيمكن لصق الإجابة في وثيقة تصميم أو التحقق منها في اختبار دون الرجوع إلى دليل أسلوب. يربط REST عمليات الاستمرارية الأربع بأفعال HTTP، إضافة إلى قراءة المجموعة التي تحتاجها كل واجهة برمجية حقيقية. فعملية الإنشاء ترتبط بـ POST على المجموعة وتعيد اصطلاحًا 201 Created، وغالبًا مع ترويسة Location تشير إلى المورد الجديد. والقراءة ترتبط بـ GET على مورد مفرد وتعيد 200 OK؛ وهي عملية آمنة ومتساوية المفعول، ولهذا يُسمح للذواكر المؤقتة وإعادة المحاولة بأن تتعامل معها بحرية. والسرد يرتبط بـ GET على المجموعة ويعيد 200 OK، وهو الموضع الذي توجد فيه معاملات الترقيم والتصفية والفرز في سلسلة الاستعلام.
لماذا PUT للتحديث، وأين يقع PATCH
تتبع هذه الأداة القراءة الأصرم لمواصفة HTTP: فـ PUT يستبدل المورد بأكمله بالتمثيل الذي يرسله العميل، وهو ما يجعله متساوي المفعول؛ إذ إن إرسال الطلب نفسه مرتين يترك الخادم في الحالة ذاتها تمامًا. هذه الخاصية هي ما يجعل PUT الخيار الاصطلاحي الافتراضي لمسار التحديث، وهي الإجابة التي تعيدها هذه الواجهة لإجراء التحديث.
حالات التكامل
توليد هياكل مسارات REST
ولّد مسارات أولية لمورد جديد مع الفعل الاصطلاحي ورمز الحالة مملوءين مسبقًا لكل إجراء من إجراءات CRUD.
تعليم اصطلاحات REST
امنح فريقك مرجعًا حتميًا واحدًا لسؤال الفعل والحالة بدل إعادة النقاش فيه في كل مراجعة.
أسئلة تقنية
هل يغطي رموز حالة الأخطاء؟
لا. إنه يجيب عن مسار النجاح الاصطلاحي فقط: فعل HTTP، ورمز حالة النجاح المعتاد، وشرح موجز للاصطلاح.
ماذا يحدث عند إجراء غير معروف؟
يفشل الطلب بخطأ invalid_input تذكر رسالته القيمة المستلمة وتسرد الإجراءات الخمسة المقبولة.