13 راهکار مفید برای ساخت یک RESTful API کاربردی و قدرتمند

• در ساده‌ترین تعریف، REST عبارت است از راه‌کارها و روش‌هایی که با استفاده از آن‌ها می‌توان اطلاعات را در شبکه انتقال داد. به عبارت دیگر، REST راهی ساده برای سازمان‌دهی تعاملات مابین سیستم‌های مجزا از یکدیگر است.
• API سرنام Application Programming Interface است که شامل متدهایی برای ارتباط با سایر کتابخانه‌ها یا برنامه‌ها است. حال اگر این اصطلاحات در کنار یکدیگر قرار بگیرند مفهومی به‌نام RESTful API به‌دست می‌آید که اشاره به سازوکارهایی برای ارتباط با سایر سرویس‌ها بر مبنای یک معماری خاص دارد. آیا تا به حال به فکر کسب اطلاعاتی در ارتباط با استانداردهای صنعت وب بوده‌اید، بهترین راهکارهای عملی برای طراحی یک RESTful API چیست؟ به لحاظ تئوری هر فردی می‌تواند به سرعت و در عرض چند دقیقه یک واسط برنامه‌نویسی کاربردی داده‌ای ( همچون Golang، Node.js یا پایتون) را پیاده‌سازی و از آن استفاده کند. با این‌حال ساخت و عرضه یک API کاربردی نیازمند رعایت برخی نکات و استانداردسازی کدنویسی‌ها است که فرایند زمان‌بری است. در این مقاله با 13 راهکار عملی برتر برای طراحی یک RESTful API قدرتمند آشنا می‌شوید، اما قبل از آن بهتر است توضیح کامل‌تری در ارتباط با RESTful API ارائه کنیم.

RESTful API چیست؟ 

• رابط برنامه‌نویسی اپلیکیشن (API) به مجموعه‎ای از روش‎های مشخص اشاره دارد که ارتباط میان مولفه‌های نرم‌افزاری را مشخص می‌کند. یک API خوب با فراهم‌سازی تمام مولفه‌های مورد نیاز اجازه می‌دهد روند ساخت و توسعه یک برنامه کاربردی ساده‎تر انجام شود. معروف‎ترین روش برای عرضه واسط‌های کاربردی برنامه‌نویسی وب REST است. یک معماری نرم‌افزاری مستقل که بسیاری از خصوصیات اساسی و پروتکل‎هایی که رفتار کلاینت‎ها و سرورها را کنترل می‌‌کند پوشش می‌دهد. از آن‌جایی که REST API‌‌ها از HTTP استفاده می‌‌کنند در عمل می‌‌توان آن‌ها را در هر زبان برنامه‌نویسی استفاده کرد. RESTful API یک سرویس وب است که با استفاده از پروتکل HTTP و اصول REST پیاده‌سازی می‌‌شود و شامل مجموعه‎ای از منابع است که متدهای (DELETE، POST، PUT، GET) را به خدمت می‌‌گیرد. این مجموعه از منابع در نهایت در یک فرمت استاندارد (معمولا XML ) که توسط بیشتر زبان‌ها و کانال‌های ارتباطی پشتیبانی می‌شوند ارائه می‌‌شود. 

بهترین راهکارهای عملی برای طراحی اولین RESTful API 

1. از متدهای HTTP درست استفاده کنید. 

• همان‌گونه که می‌دانید توسعه‌دهندگان می‌توانند برای تغییر و اصلاح منابع از متدهای GET، PUT، POST، PATCH و DELETE استفاده کنند. هنوز هم خیلی از توسعه‌دهندگان متدهای GET و POST یا PUT و PATCH را به اشتباه به جای یکدیگر استفاده می‌کنند. اغلب شاهد هستیم که توسعه‌دهندگان برای بازیابی داده‌ها از یک درخواست POST استفاده می‌کنند. علاوه بر این مشاهده می‌شود که توسعه‌دهندگان از یک درخواست PUT استفاده می‌کنند که منبع را جایگزین می‌کند، در حالی که تنها به دنبال به‌روزرسانی فیلدی از یک منبع بودند. مطمئن شوید كه حتما از یک متد HTTP صحیح استفاده می‌کنید، زیرا این موضوع سردرگمی‌های زیادی را برای توسعه‌دهندگانی که از RESTful API شما استفاده می‌کنند به همراه خواهد داشت. بهترین کار این است که طراحی را مطابق با استانداردهای منتشر شده انجام دهید. 

2. اصول نام‌گذاری را رعایت کنید. 

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

 api.com/addNewAuthor *

 api.com/getAuthorByID/3 *

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

* POST api.com/authors
* GET api.com/authors/3

• اگر بخواهیم به تمام کتاب‌هایی که نویسنده با شناسه 3 تا به‌حال نوشته دسترسی پیدا کنیم چگونه باید واسط برنامه‌نویسی کاربردی خود را طراحی کنیم؟ یک راه‌حل می‌تواند به شرح زیر باشد: 

* GET api.com/auth‌ors/3/books

• اگر بخواهیم یک کتاب با شناسه 5 مربوط به یک نویسنده با شناسه 3 را پاک کنیم چه کاری باید انجام دهیم؟ دوباره باید همان روش ساختاری را دنبال کنیم تا نقطه پایانی زیر را تشکیل دهیم:

* DELETE api.com/authors/3/books/5

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

3. از منابع جمعی استفاده کنید 

• منابع باید همیشه به صورت جمع استفاده شوند، اما چرا؟ تصور کنید که می‌خواهید اطلاعات تمام نویسندگان را بازیابی کنید. بنابراین باید این نقطه پایانی را فراخوانی کنید: GET api.com/authors
• وقتی این درخواست را مشاهده می‌کنید، نمی‌توانید اعلام کنید که آیا پاسخ API تنها شامل یک نویسنده می‌شود یا تمام آن‌ها را شامل می‌شود. به همین دلیل نقاط پایانی API باید از منابع جمعی استفاده کنند.

4. از کدهای وضعیت به شکل صحیح استفاده کنید 

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

•  200 (OK): درخواست با موفقیت به انجام رسیده و تکمیل شده است.
• 201 (Created): منبع با موفقیت ساخته شده است. 
• 400 (Bad Request): خطایی در سمت کلاینت اتفاق افتاده است. به این معنی که  درخواست ناقص بوده یا پارامترهای درخواست درست وارد نشده‌اند. 
• 401 (Unauthorized): شما سعی کردید به منبعی دسترسی پیدا کنید که اجازه آن‌را ندارید.
• 404 (Not Found): منبع درخواست شده وجود ندارد.
•  500 (Internal Server Error): سرور در اجرای درخواست با مشکل روبرو شده است. 

** برای دریافت فهرست کامل کدهای وضعیت می‌توانید به صفحهMozilla Developers به نشانی: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status مراجعه کنید.

5. اصول نوشتن صحیح اسامی‌ را رعایت کنید 

• اغلب اوقات یک  RESTful API داده‌های JSON را به‌کار می‌گیرد. بنابراین باید از قائده نوشتن چند کلمه پشت سرهم بدون فاصله به شکلی که حرف اول هر کلمه با حرف بزرگ نوشته شود (camelCase) پیروی کرد. با این‌حال، دقت کنید هر زبان برنامه‌نویسی قواعد نام‌گذاری مختص به خود را دارد.

6. وظایفی همچون جست‌وجو، تقسیم بندی تعداد صفحات، فیلترینگ و مرتب‌سازی را درست مدیریت کنید.

• کارهایی همچون جست‌وجو، تقسیم‌بندی تعداد صفحات، فیلترینگ و مرتب‌سازی، نقاط پایانی جداگانه‌ای را ارائه نمی‌کنند. یک چنین کارهایی را می‌توان از طریق به‌کارگیری پارامترهای اجرای محاوره‌ که توسط درخواست API فراهم می‌شود انجام داد. 
• به‌طور مثال، فرض کنید، در نظر داریم نام تمام نویسندگان را بر اساس حروف الفبا استخراج کنیم. درخواست API شما باید شبیه به حالت زیر باشد: 

* api.com/authors?sort=name_asc

• علاوه بر این، اگر بخواهیم یک نویسنده با نام Michiel را بازیابی کنیم درخواست باید شبیه به حالت زیر باشد: 

* api.com/authors?search=Michiel

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

7. API خود را نسخه‌بندی کنید 

• بهتر است API خود را به صورت نسخه‌بندی شده (versioning) آماده و منتشر کنید. نسخه‌بندی بهترین روش اطلاع‌رسانی در ارتباط با تغییرات پیاده‌سازی شده است. اغلب شماره نسخه API در آدرس اینترنتی API مشابه با ترکیب نحوی زیر قرار می‌گیرد:

* api.com/v1/authors/3/books

8. فراداده را از طریق سرآیندهای HTTP ارسال کنید 

• سرآیندهای HTTP به کلاینت اجازه می‌دهد تا همراه با درخواست خود اطلاعات اضافی دیگری را هم ارسال کند. به‌طور مثال، از سرآیند Authorization معمولا برای ارسال داده‌های هویت‌سنجی برای دسترسی به API استفاده می‌شود. برای مشاهده فهرست کامل سرآیندهایHTTP به آدرس https://en.wikipedia.org/wiki/List_of_HTTP_header_fields مراجعه کنید.

9. Rate limiting

• Rate limiting یک رویکرد جالب توجه برای کنترل تعداد درخواست‌های مرتبط با هر کلاینت است. از مهم‌ترین و کاربردی‌‌ترین سرآیندهای Rate limiting که توسط سرور باز گردانده می‌شوند به موارد زیر می‌توان اشاره کرد:
•  X-Rate-Limit-Limit: تعداد درخواست‌هایی که یک کلاینت می‌تواند در یک بازه زمانی مشخص ارسال کند را اعلام می‌کند.
•  X-Rate-Limit-Remaining: تعداد درخواست‌های باقی مانده در یک بازه زمانی مشخص که یک کلاینت می‌تواند ارسال کند را اعلام می‌کند.
•  X-Rate-Limit-Reset: به کاربر اعلام می‌کند چه زمانی rate limit ریست خواهد شد.

10. کنترل معنادار خطا

در صورت بروز مشکل، مهم است با یک پیغام معنادار و قابل فهم خطا را به توسعه‌دهنده اعلام کنید. به‌طور مثال، Twilio API فرمت خطای زیر را بازمی‌گرداند:

{
    “status”: 400,
    “message”: “Resource books does not exist”,
    “code”: 24801,
    “more_info”: “api.com/docs/errors/24801”

}

در این مثال، سرور یک کد وضعیت را به همراه یک پیغام قابل فهم باز می‌گرداند. همچنین یک کد خطای داخلی نیز به توسعه‌دهنده ارسال می‌شود تا به دنبال یک خطای مشخص بگردد. رویکرد فوق به توسعه‌دهنده امکان می‌دهد به سرعت اطلاعات بیشتری در مورد خطای تولید شده پیدا کند.

11. چهارچوب API درست را انتخاب کنید 

• چهارچوب‌های زیادی هستند که برای زبان‌های برنامه‌نویسی مختلف در نظر گرفته شده‌اند. مهم است که چهارچوبی انتخاب کنید که از بهترین راهکارهای عملی RESTful API پشتیبانی کند. 
• در مورد Node.js، توسعه‌دهندگان بک-اند به‌کارگیری Express.js (https://expressjs.com/) را ترجيح می‌دهند، در حالی که برای پایتون Falcon (https://falconframework.org/) یک گزینه عالی محسوب می‌شود.

12. API خود را مستند‌سازی کنید 

• در نهایت، برای پروژه خود سند تهیه کنید. هنوز هم راهکار فوق ساده‌ترين روش برای انتقال اطلاعات مربوط به API تازه تولید شده است. حتا اگر API شما تمام استانداردهای مطرح شده برای RESTful APIها را رعایت کند، بازهم کار ارزشمندی است که بخشی از وقت خود را صرف مستندسازی مولفه‌ها و عناصر به کار رفته در API کنید. به توسعه‌دهندگانی که قرار است با شما همکاری کنند یا از محصول شما استفاده کنند فکر کنید. مستندات زمان موردنیاز برای یادگیری API را کاهش می‌دهد.

13. API را تا حد امکان ساده کنید

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