بهترین راهکارها برای نام‌گذاری API

خطوط کد

هنگام نام‌گذاری درخواست‌های نقاط پایانی API، مهم است که از بهترین روش‌ها پیروی کنید تا API شما شهودی، سازگار و کاربرپسند باشد. در ادامه راهنماها و مثال‌هایی ارائه شده‌اند که به شما کمک می‌کنند نقاط پایانی API خود را به طور مؤثر نام‌گذاری کنید:

  1. از اسامی (Nouns) برای منابع استفاده کنید.
    نقاط پایانی باید نمایانگر منابع (اسامی) باشند نه اقدامات (افعال). برای مثال، از /users به جای /getUsers استفاده کنید.

  2. از اسامی جمع برای مجموعه‌ها استفاده کنید.
    وقتی به یک مجموعه از منابع اشاره می‌کنید، از اسامی جمع (مانند /users) استفاده کنید. برای یک منبع خاص، از فرم مفرد همراه با شناسه آن استفاده کنید (مثلاً /users/{id}).

  3. از روش‌های HTTP برای تعریف عملیات استفاده کنید.

    • GET. برای بازیابی یک منبع یا مجموعه‌ای از منابع (مثلاً GET /users, GET /users/{id}).
    • POST. برای ایجاد یک منبع جدید (مثلاً POST /users).
    • PUT یا PATCH. برای به‌روزرسانی یک منبع موجود (مثلاً PUT /users/{id} یا PATCH /users/{id}).
    • DELETE. برای حذف یک منبع (مثلاً DELETE /users/{id}).

  4. ساختار سلسله‌مراتبی را رعایت کنید.
    از یک سلسله‌مراتب شفاف و منطقی برای نمایش روابط بین منابع استفاده کنید (مثلاً /users/{id}/posts برای نمایش پست‌های یک کاربر خاص).

  5. از نام‌گذاری یکسان و سازگار استفاده کنید.
    از یک سبک نام‌گذاری ثابت، مانند snake_case یا kebab-case، استفاده کرده و در تمام API این روش را رعایت کنید (مثلاً /user_profiles یا /user-profiles).

  6. از کاراکترهای خاص و فضاها اجتناب کنید.
    از خط تیره (-) برای جدا کردن کلمات به جای فاصله یا خط زیرین (_) در مسیرهای URL استفاده کنید (مثلاً /user-profiles به جای /user_profiles).

  7. آن را ساده و شهودی نگه دارید.
    نام‌ها باید به‌راحتی قابل درک و به خاطر سپردن باشند. از اصطلاحات پیچیده یا بیش از حد فنی خودداری کنید.

  8. نسخه‌بندی API.
    نسخه‌بندی را در مسیرهای نقاط پایانی قرار دهید تا در آینده بتوانید تغییرات ایجاد کنید بدون اینکه مشتریان فعلی را دچار مشکل کنید (مثلاً /v1/users).

  9. توضیح عملیات با پارامترهای کوئری.
    به جای استفاده از افعال در مسیرهای نقاط پایانی، از پارامترهای کوئری برای فیلتر کردن، مرتب‌سازی یا جستجو استفاده کنید (مثلاً GET /users?status=active).

نمونه‌هایی از نام‌گذاری مناسب نقاط پایانی API

در اینجا چند نمونه از نقاط پایانی API با ساختار خوب آورده شده است که از این بهترین روش‌ها پیروی می‌کنند:

مدیریت کاربران:

  • GET /v1/users – بازیابی لیست کاربران.
  • GET /v1/users/{id} – بازیابی کاربر خاص با شناسه.
  • POST /v1/users – ایجاد یک کاربر جدید.
  • PUT /v1/users/{id} – به‌روزرسانی اطلاعات یک کاربر.
  • DELETE /v1/users/{id} – حذف یک کاربر.

احراز هویت:

  • POST /v1/auth/login – ورود کاربر.
  • POST /v1/auth/register – ثبت‌نام کاربر.
  • POST /v1/auth/logout – خروج کاربر.

روابط منابع:

  • GET /v1/users/{id}/posts – بازیابی پست‌های ایجاد شده توسط یک کاربر خاص.
  • POST /v1/users/{id}/posts – ایجاد یک پست جدید برای یک کاربر خاص.

صفحه‌بندی و فیلتر کردن:

  • GET /v1/users?page=2&limit=10 – صفحه‌بندی کاربران با ۱۰ کاربر در هر صفحه.
  • GET /v1/posts?sort=desc&category=tech – بازیابی پست‌ها به ترتیب نزولی تاریخ و فیلتر بر اساس دسته‌بندی تکنولوژی.

عملیات پیچیده با نام‌گذاری شفاف:

  • POST /v1/orders/{id}/cancel – لغو یک سفارش.
  • PUT /v1/users/{id}/password – به‌روزرسانی رمز عبور کاربر.

مدیریت خطاها و وضعیت‌ها:

  • GET /v1/orders?status=pending – بازیابی سفارش‌ها با وضعیت در انتظار.

نتیجه‌گیری

با پیروی از این اصول، می‌توانید API‌ای شفاف، سازگار و کاربرپسند ایجاد کنید که برای توسعه‌دهندگان شهودی و کارآمد باشد. نام‌گذاری نقاط پایانی در طراحی API بسیار مهم است، زیرا شفافیت و کاهش سردرگمی را فراهم می‌کند و استفاده از API را آسان‌تر می‌سازد.

©دوات با هدف دسترس‌پذیر کردن دانش انگلیسی در حوزه صنعت نرم‌افزار وجود آمده است. در این راستا از هوش مصنوعی برای ترجمه گلچینی از مقالات مطرح و معتبر استفاده می‌شود. با ما در تماس باشید و انتقادات و پیشنهادات خود را از طریق صفحه «تماس با ما» در میان بگذارید.