فیس بوک ، GitHub ، گوگل و بسیاری از غول های دیگر به روشی برای سرویس دهی و مصرف داده نیاز دارند. RESTful API هنوز هم یکی از بهترین گزینه ها در چشم انداز توسعه امروز برای سرویس دهی و مصرف داده است.
اما آیا تا به حال به یادگیری استانداردهای صنعت فکر کرده اید؟ بهترین روش ها برای طراحی RESTful API کدامند؟ از نظر تئوری ، هر کسی می تواند به سرعت API داده را در کمتر از پنج دقیقه بچرخاند – چه Node.js ، Golang یا Python.
ما 13 بهترین روشی را که باید هنگام ساخت RESTful API در نظر بگیرید بررسی خواهیم کرد. اما در ابتدا ، بیایید سریع یک RESTful API را روشن کنیم.
RESTful API چیست؟
RESTful API باید محدودیت های زیر را برآورده کند تا RESTful API نامیده شود.
-
سرور مشتری: A RESTful API مدل مشتری-سرور را دنبال می کند که در آن سرور داده را ارائه می دهد و کلاینت ها برای مصرف داده به سرور متصل می شوند. تعامل بین سرویس گیرنده و سرور از طریق درخواست های HTTP (S) انجام می شود که داده های درخواستی را منتقل می کنند.
-
بی تابعیت: مهمتر از همه ، یک API RESTful باید بدون حالت باشد. هر درخواست به عنوان یک درخواست مستقل در نظر گرفته می شود. سرور نباید هیچ وضعیت داخلی را که ممکن است در نتیجه درخواستهای آینده تأثیر بگذارد ، پیگیری کند.
-
رابط یکنواخت: سرانجام ، یکنواختی نحوه تعامل مشتری و سرور را مشخص می کند. API های RESTful بهترین روش ها را برای نامگذاری منابع تعریف می کنند اما عملیات ثابت HTTP را تعریف می کنند که به شما امکان می دهد منابع را تغییر دهید / تعامل کنید. عملیات HTTP زیر را می توان در RESTful API ها مشاهده کرد:
- درخواست GET: یک منبع را بازیابی کنید
- درخواست POST: ایجاد یک منبع یا ارسال اطلاعات به API
- درخواست PUT: منبعی را ایجاد یا جایگزین کنید
- درخواست PATCH: منبع موجود را به روز کنید
- درخواست حذف: یک منبع را حذف کنید
با این درک عمیق تر از ویژگی های RESTful API ، وقت آن است که درباره بهترین روش های RESTful API بیشتر بدانید.
بهترین شیوه ها برای طراحی اولین API آرام شما
این مقاله لیستی قابل اجرا از 13 بهترین روش را به شما ارائه می دهد. بیایید کشف کنیم!
1. به درستی از روشهای HTTP استفاده کنید
ما قبلاً در مورد روشهای احتمالی HTTP که می توانید برای تغییر منابع استفاده کنید بحث کردیم: GET ، POST ، PUT ، PATCH و DELETE.
هنوز ، بسیاری از توسعه دهندگان تمایل به سو abuse استفاده از GET و POST یا PUT و PATCH دارند. غالباً مشاهده می کنیم که توسعه دهندگان از یک درخواست POST برای بازیابی داده ها استفاده می کنند. علاوه بر این ، مشاهده می کنیم که توسعه دهندگان از یک درخواست PUT استفاده می کنند که جایگزین منبع می شود در حالی که آنها فقط می خواستند یک قسمت واحد را برای آن منبع به روز کنند.
اطمینان حاصل کنید که از روش صحیح HTTP استفاده کنید زیرا سردرگمی بسیاری را برای توسعه دهندگان با استفاده از RESTful API شما ایجاد می کند. بهتر است به رهنمودهای مورد نظر پایبند باشید.
2. نامگذاری قراردادها
شناخت RENSEL API نامگذاری به شما در طراحی API به صورت سازمان یافته کمک زیادی می کند. با توجه به منابعی که خدمت می کنید RESTful API را طراحی کنید.
به عنوان مثال ، API شما نویسندگان و کتاب ها را مدیریت می کند (بله ، یک مثال کلاسیک). اکنون ، ما می خواهیم یک نویسنده جدید اضافه کنیم یا به یک نویسنده با شناسه دسترسی پیدا کنیم 3. برای این منظور می توانید مسیرهای زیر را طراحی کنید:
- api.com/addNewAuthor
- api.com/getAuthorByID/3
یک API را تصور کنید که میزبان بسیاری از منابع است که هر یک از آنها دارای ویژگی های زیادی هستند. لیست نقاط پایانی ممکن بی پایان خواهد شد و چندان کاربر پسند نیست. بنابراین ما به یک روش سازمان یافته و استانداردتر در طراحی نقاط انتهایی API نیاز داریم.
بهترین شیوه های RESTful API توصیف می کنند که یک نقطه پایانی باید با نام منبع شروع شود ، در حالی که عملیات HTTP عمل را توصیف می کند. اکنون دریافت می کنیم:
- api.com/ نویسندگان پست
- api.com/authors/3 را دریافت کنید
اگر بخواهیم به تمام نویسندگان کتاب با شناسه دسترسی پیدا کنیم چه می کنیم 3 تا حالا نوشته؟ همچنین برای این مورد ، API های RESTful یک راه حل دارند:
- api.com/authors/3/books را دریافت کنید
سرانجام ، اگر می خواهید کتابی با شناسه حذف کنید ، چه می کنید 5 برای نویسنده ای با شناسنامه 3. باز هم ، بیایید همان روش ساختاری را دنبال کنیم تا نقطه پایانی زیر را تشکیل دهیم:
- حذف api.com/authors/3/books/5
به طور خلاصه ، از عملیات HTTP و روش ساختاری نقشه برداری منابع استفاده کنید تا یک مسیر پایان نهایی قابل خواندن و قابل فهم باشد. مزیت بزرگ این روش این است که هر توسعه دهنده می داند که چگونه API های RESTful طراحی شده اند و آنها می توانند بدون نیاز به خواندن مستندات شما در هر نقطه انتهایی ، بلافاصله از API استفاده کنند.
3. از منابع جمع استفاده کنید
منابع همیشه باید از شکل جمع خود استفاده کنند. چرا؟ تصور کنید می خواهید همه نویسندگان را بازیابی کنید. بنابراین ، شما می توانید با نقطه پایانی زیر تماس بگیرید: GET api.com/authors.
وقتی درخواست را می خوانید ، نمی توانید تشخیص دهید که پاسخ API فقط شامل یک یا همه نویسندگان است. به همین دلیل ، نقاط پایانی API باید از منابع جمع استفاده کنند.
4. استفاده صحیح از کدهای وضعیت
کدهای وضعیت فقط برای سرگرمی نیستند. آنها هدف مشخصی دارند. کد وضعیت درمورد موفقیت درخواست خود به مشتری اطلاع می دهد.
متداول ترین دسته های کد وضعیت عبارتند از:
- 200 (تأیید): درخواست با موفقیت رسیدگی و تکمیل شد.
- 201 (ایجاد شده): ایجاد موفقیت آمیز یک منبع را نشان می دهد.
- 400 (درخواست بد): خطای سمت مشتری را نشان می دهد. به این معنی که درخواست نامناسب شده یا پارامترهای درخواست را از دست داده است.
- 401 (غیر مجاز): سعی کردید به منبعی دسترسی پیدا کنید که اجازه آن را ندارید.
- 404 (یافت نشد): منبع درخواستی وجود ندارد.
- 500 (خطای داخلی سرور): هر زمان که سرور هنگام اجرای درخواست استثنایی را مطرح کند.
لیست کاملی از کدهای وضعیت را می توانید در اینجا پیدا کنید توسعه دهندگان موزیلا. فراموش نکنید که کد وضعیت “من یک قوری هستم” (418) را بررسی کنید.
5- قراردادهای پوشش را دنبال کنید
معمولاً ، یک RESTful API داده های JSON را ارائه می دهد. بنابراین ، کنوانسیون پوشش camelCase باید انجام شود. با این حال ، زبان های برنامه نویسی مختلف استفاده می کنند قراردادهای مختلف نامگذاری.
6. نحوه کنترل ، صفحه بندی ، فیلتر و مرتب سازی
اعمالی مانند جستجو ، صفحه بندی ، فیلتر کردن و مرتب سازی ، نقاط انتهایی جداگانه را نشان نمی دهند. این اقدامات می توانند با استفاده از پارامترهای جستجوی ارائه شده با درخواست API انجام شوند.
به عنوان مثال ، بیایید همه نویسندگان را که به ترتیب صعودی مرتب شده اند بازیابی کنیم. درخواست API شما باید به این شکل باشد: api.com/authors?sort=name_asc.
علاوه بر این ، من می خواهم نویسنده ای را با نام “میشیل” بازیابی کنم. درخواست به این شکل است api.com/authors?search=Michiel.
خوشبختانه بسیاری از پروژه های API دارای قابلیت جستجو ، صفحه بندی ، فیلتر و مرتب سازی داخلی هستند. این باعث صرفه جویی در وقت شما می شود.
7. نسخه API
من این را اغلب نمی بینم ، اما بهترین نسخه برای نسخه دهی API شما است. این یک روش موثر برای برقراری ارتباط با شکستن تغییرات به کاربران شما است.
غالباً ، شماره نسخه API در URL API گنجانده شده است ، مانند این: api.com/v1/authors/3/books.
سرصفحه های HTTP به مشتری اجازه می دهد تا اطلاعات اضافی را با درخواست خود ارسال کند. به عنوان مثال Authorization از سربرگ معمولاً برای ارسال داده های تأیید اعتبار برای دسترسی به API استفاده می شود.
لیست کاملی از همه هدرهای HTTP را می توان یافت اینجا.
9. محدود کردن نرخ
محدود کردن نرخ یک روش جالب برای کنترل تعداد درخواست ها برای هر مشتری است. اینها هدرهای محدود کننده نرخ ممکن است که سرور شما می تواند برگرداند:
- X-Rate-Limit-Limit: تعداد درخواستهایی را که مشتری می تواند در یک بازه زمانی مشخص ارسال کند ، بیان می کند.
- X-Rate-Limit-Remaining: بیان می کند که مشتری در بازه زمانی فعلی هنوز می تواند درخواست های زیادی ارسال کند.
- X-Rate-Limit-Reset: به مشتری می گوید چه زمانی محدودیت نرخ مجدداً تنظیم می شود.
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 ، توسعه دهندگان back-end دوست دارند از آن استفاده کنند Express.js، در حالی که برای پایتون ، شاهین یک گزینه عالی است
12. API خود را مستند کنید
دست آخر ، مستندات را بنویسید! شوخی نمی کنم؛ هنوز هم یکی از ساده ترین راه ها برای انتقال دانش در مورد API تازه توسعه یافته شماست.
اگرچه API شما از بهترین روشهای توصیف شده برای RESTful API پیروی می کند ، با این وجود ارزش این را دارد که عناصر مختلفی مانند منابعی را که API شما کنترل می کند یا محدودیت های نرخ برای سرور شما ثبت کند.
به توسعه دهندگان خود فکر کنید. مستندات مدت زمان لازم برای یادگیری API شما را به شدت کاهش می دهد.
13. ساده نگه دارید!
API خود را بیش از حد پیچیده نکنید و منابع را ساده نگه دارید. تعریف مناسب از منابع مختلفی که API شما مدیریت می کند به شما کمک می کند تا از مشکلات مربوط به منابع در آینده جلوگیری کنید. منابع خود را تعریف کنید ، اما همچنین ویژگی های آن و روابط بین منابع را به طور دقیق تعریف کنید. به این ترتیب دیگر جایی برای بحث در مورد چگونگی اتصال منابع مختلف وجود ندارد.
اگر این مقاله را در توضیح بهترین روش های API دوست داشتید ، ممکن است از یادگیری ساخت یک API RESTful از ابتدا لذت ببرید.
