نکاتی برای طراحی RESTful API

در دنیای توسعه وب، RESTful API ها به عنوان API ، نقشی محوری در تسهیل ارتباط روان بین کلاینت و سرور ایفا می کنند. می توان کلاینت را به عنوان بخش فرانت اند و سرور را به عنوان بخش بک اند در نظر گرفت.

برخلاف تصور رایج، تبادل اطلاعات بین کلاینت و سرور به صورت مستقیم انجام نمی شود. در این میان، واسطه ای به نام API (Application Programming Interface) وظیفه برقراری ارتباط و انتقال داده ها را بر عهده دارد.

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

RESTful API چیست؟

REST مخفف Representational State Transfer است. این یک سبک معماری نرم افزاری است که در سال 2000 توسط روی فیلدینگ برای طراحی و توسعه برنامه در سطح وب ایجاد شد. این معماری در اکثر اوقات همراه با پروتکل HTTP برای ساخت API در بستر وب استفاده می شود. هر API (Application Programming Interface) که از اصول طراحی REST پیروی کند، RESTful نامیده می شود.

نکاتی برای طراحی RESTful API های بهتر

استفاده از JSON برای رد و بدل اطلاعات

برای رد و بدل اطلاعات در REST API ها، هم برای ارسال درخواست (Request) و هم برای دریافت پاسخ (Response)، بهتر است از فرمت JSON استفاده شود. راه های دیگری نیز برای انتقال داده ها وجود دارد؛ مانند استفاده از XML، اما JSON به دلیل سادگی، حجم کم و سرعت پردازش بالا، برای ها مناسب تر است. بنابراین، توصیه می شود برای رد و بدل اطلاعات از فرمت JSON استفاده گردد. علاوه بر این، JSON توسط تعداد زیادی از زبان های برنامه نویسی پشتیبانی می شود.

استفاده از اسامی به جای افعال در Endpoint ها

هنگام نامگذاری URL های RESTful API، باید از تکرار افعال در URL خودداری کرد. دلیل این امر آن است که متدهای HTTP (GET، POST، PUT، PATCH) به طور ذاتی نوع عمل مورد نظر را نشان می دهند.

بهترین روش استفاده از اسامی منطقی و توصیفی در URL ها و مشخص کردن نوع عملیات (افعال) با استفاده از متدهای HTTP است.

مزایای این روش:

• انسجام: این روش با استانداردهای طراحی REST مطابقت دارد و به کاربران و توسعه دهندگان کمک می کند تا به سرعت API را درک کنند.
• خوانایی: URL ها کوتاه تر و خواناتر می شوند.

مثال ها:

نامگذاری غلط:

• GET http://example-api.com/getusers
• POST http://example-api.com/createuser

نامگذاری صحیح:

• GET http://example-api.com/users (برای دریافت لیست کاربران)
• POST http://example-api.com/users (برای ایجاد یک کاربر جدید)

در مثال های بالا، URL ها با اسامی منطقی (users) نامگذاری شده اند و متدهای HTTP (GET، POST) نوع عملیات را مشخص می کنند.

نامگذاری مجموعه ها با اسامی جمع

هنگامی که داده‌های RESTful API خود را به عنوان مجموعه‌ای از منابع مختلف در نظر می‌گیرید، نامگذاری آنها با اسامی جمع، وضوح و درک را برای کاربران و توسعه‌دهندگان به ارمغان می‌آورد و با استانداردهای طراحی REST  نیز سازگار است.

فرض کنید endpoint مانند https://example.com/post/123 دارید. این endpoint ممکن است برای حذف یک پست با درخواست DELETE یا به‌روزرسانی آن با درخواست PUT یا PATCH مناسب باشد. با این حال، به کاربر نمی‌گوید که پست‌های دیگری هم در این مجموعه وجود دارد.

برای حل این مشکل، باید از اسامی جمع برای مجموعه‌ها استفاده کنید. به جای https://example.com/post/123، از https://example.com/posts/123 استفاده کنید.

این تغییر ساده، فواید متعددی دارد:

• وضوح: نامگذاری با اسامی جمع به وضوح نشان می‌دهد که با یک مجموعه از منابع سروکار داریم، نه فقط یک منبع واحد.
• درک: این امر درک ساختار داده‌ها و نحوه ارتباط منابع با یکدیگر را برای کاربران و توسعه‌دهندگان آسان‌تر می‌کند.

استفاده از کدهای وضعیت در مدیریت خطا

استفاده از کدهای وضعیت HTTP در هنگام کار با RESTful API ها، روشی استاندارد و کارآمد برای مدیریت خطاها و ارائه اطلاعات مفید به کاربران و توسعه دهندگان است. با ارسال کد وضعیت مناسب در هر پاسخ، می توانید به وضوح نشان دهید که چه اتفاقی در جریان است و آیا درخواست با موفقیت انجام شده یا خیر.

جدول زیر محدوده های مختلف کدهای وضعیت HTTP و معنای آنها نشان می دهد:

لیست کاملی از کدهای وضعیت HTTP و توضیحات مربوط به آنها را می توانید در https://en.wikipedia.org/wiki/List_of_HTTP_status_codes مشاهده کنید.

مزایای استفاده از کدهای وضعیت:

• آگاهی رسانی: کدهای وضعیت به کاربران و توسعه دهندگان اطلاع می دهند که چه اتفاقی در جریان است و آیا درخواست با موفقیت انجام شده یا خیر.
• عیب یابی: کدهای وضعیت می توانند به عنوان سرنخی برای عیب یابی و رفع مشکلات API عمل کنند.
• استانداردسازی: استفاده از کدهای وضعیت استاندارد HTTP، ثبات و انسجام را در بین API ها ایجاد می کند و به کاربران و توسعه دهندگان در درک و استفاده از API های مختلف کمک می کند.

سلسله مراتب Endpoint ها: سازماندهی RESTful API برای درک آسان تر

اغلب، endpoint های مختلف می توانند به یکدیگر مرتبط باشند، بنابراین باید آنها را درون هم قرار دهید تا درک آنها آسان تر شود.

به عنوان مثال، در مورد یک پلتفرم وبلاگ نویسی چندکاربره، ممکن است نوشته های مختلف توسط نویسندگان متفاوتی نوشته شده باشند، بنابراین یک endpoint مانند https://example.com/posts/author در این مورد یک سلسله مراتب معتبر را نشان می دهد.

در همین راستا، ممکن است نوشته ها دارای نظرات جداگانه باشند، بنابراین برای دریافت نظرات، یک endpoint مانند https://example.com/posts/postId/comments منطقی به نظر می رسد.

باید از سلسله مراتب بیش از 3 سطح عمیق اجتناب کنید، زیرا این می تواند باعث کاهش خوانایی RESTful API شود.

استفاده از query برای فیلتر، مرتب‌سازی و صفحه‌بندی جهت دریافت داده‌های درخواستی

بعضی از RESTful API ها حجیم بوده و شامل داده‌های انبوهی هستند. فرض کنید می‌خواهیم لیست کاملی از یک نوع داده خاص را دریافت کنیم. در این حالت، به دلیل حجم زیاد داده‌ها، فرآیند مذکور زمان‌بر خواهد بود. راه‌حل مناسب در این شرایط، استفاده از فیلتر و صفحه‌بندی برای دریافت بخش کوچکی از اطلاعات در هر درخواست است.

با استفاده از قابلیت‌های فیلتر، مرتب‌سازی و صفحه‌بندی روی مجموعه داده‌های یک RESTful API، می‌توان تنها داده‌های مورد نیاز را از API دریافت، مرتب و در صفحات مجزا ارائه کرد. این امر از اشباع سرور با حجم زیاد درخواست‌ها جلوگیری می‌کند.

به عنوان مثال، endpoint زیر فقط پست‌هایی را که دارای تگ “javascript” هستند، فیلتر و بازیابی می‌کند:

https://example.com/posts?tags=javascript