دليل تصميم REST API
الواجهة البرمجية الجيدة متوقعة ومتسقة وسهلة التطوير. يغطي هذا الدليل القرارات التصميمية الأساسية التي تفصل واجهة قابلة للصيانة عن أخرى تُتعب كل مطوّر عميل.
نمذج الموارد لا الأفعال
سمِّ نقاط النهاية بأسماء (موارد) واستخدم وسائل HTTP للأفعال: GET للقراءة و POST للإنشاء و PUT/PATCH للتحديث و DELETE للحذف. واجعل الروابط هرمية ومتسقة.
استخدم رموز الحالة والأخطاء جيدًا
أعِد رموز حالة HTTP الصحيحة (200 و201 و400 و401 و404 و422 و500) وجسم خطأ متسق يحوي رمزًا قابلًا للقراءة آليًا ورسالة بشرية. لا تُعِد 200 لخطأ أبدًا.
الإصدارات والتقسيم والتوثيق
أصدِر واجهتك (مثل /v1) لتتمكن من التطوير دون كسر العملاء، وقسّم المجموعات الكبيرة، وانشر التوثيق. تسلّم ويبكس واجهات موثّقة ومُصدَّرة افتراضيًا.
الأسئلة الشائعة
هل أُصدِر واجهتي البرمجية؟
نعم، خصوصًا للواجهات العامة. تتيح الإصدارات إدخال تغييرات كاسرة دون إزعاج العملاء الحاليين.
كيف تعالج الواجهات الأخطاء؟
برموز حالة HTTP الصحيحة وجسم خطأ JSON متسق يحوي رمزًا ورسالة واضحة.