الواجهة هي لغة التخاطب بين نظامك وأي تطبيق آخر. وكلما كانت متوقعة، قلّت الأخطاء وسهل التطوير عليها لسنوات.

الأسماء للموارد والأفعال للطرق

استخدم أسماء جمع للموارد، وطرق HTTP للفعل:

  • GET /invoices قائمة الفواتير.
  • POST /invoices إنشاء فاتورة.
  • GET /invoices/42 فاتورة محددة.
  • PATCH /invoices/42 تعديل جزئي.
  • DELETE /invoices/42 حذف.

رموز الحالة بصدق

200 للنجاح، 201 للإنشاء، 400 لطلب خاطئ، 401 لعدم المصادقة، 403 لعدم الصلاحية، 404 لغير الموجود، 422 لبيانات غير صالحة. لا تُرجع 200 مع رسالة خطأ داخل المتن.

أخطاء مفهومة

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

الأمان

  1. اطلب مصادقة لكل ما هو خاص، ولا تضع المفاتيح في الروابط.
  2. تحقق من الصلاحية على كل مورد، لا على الواجهة فقط.
  3. تحقق من المدخلات واستخدم استعلامات مهيأة.
  4. حدّد معدل الطلبات لتخفيف إساءة الاستخدام.

الإصدارات والصفحات

ضع رقم الإصدار في المسار (/v1) لتتطور دون كسر العملاء، وقسّم القوائم الطويلة إلى صفحات.

واجهة لا تفاجئ مستخدمها هي واجهة جيدة التصميم.