چرا نوشتن طرح‌های REST-API تمیز مهم است
در دنیای به هم پیوسته امروزی، API های REST که به خوبی طراحی شده اند، ستون فقرات برنامه های کاربردی کارآمد و مقیاس پذیر هستند.
نوشتن طرح‌های REST API تمیز به چند دلیل حیاتی است:
-
قابلیت استفاده پیشرفته: یک API خوب طراحی شده بصری و آسان برای استفاده است، و آن را برای توسعه دهندگان در تمام سطوح مهارت قابل دسترسی می کند. این یکپارچگی را ساده می کند و منحنی یادگیری را کاهش می دهد.
-
قابلیت نگهداری بهبود یافته: کد پاک با آسان‌تر کردن شناسایی و رفع اشکالات، افزودن ویژگی‌ها و مقیاس‌بندی API، قابلیت نگهداری را افزایش می‌دهد. این امر ثبات طولانی مدت را تضمین می کند و هزینه های توسعه را کاهش می دهد.
-
افزایش امنیت: یک API با ساختار مناسب با مکانیسم‌های احراز هویت و مجوز مناسب به جلوگیری از دسترسی غیرمجاز، نقض داده‌ها و سایر آسیب‌پذیری‌های امنیتی کمک می‌کند.
-
عملکرد پیشرفته: طراحی تمیز با استفاده از ساختارهای داده کارآمد، اجتناب از تماس‌های غیر ضروری و به حداقل رساندن تأخیر، عملکرد را بهینه می‌کند. این یک تجربه کاربری یکپارچه را فراهم می کند و عملکرد کلی برنامه را بهبود می بخشد.
-
کاهش زمان توسعه: مشخصات API به خوبی تعریف شده و مستندات واضح با حذف حدس و گمان و کاهش نیاز به آزمایش گسترده، توسعه سریعتر را امکان پذیر می کند. این باعث صرفه جویی در زمان و منابع ارزشمند توسعه می شود.
-
مقیاس پذیری بهبود یافته: طراحی تمیز با ارائه یک معماری مدولار که می تواند به راحتی گسترش یابد تا ترافیک افزایش یافته یا ویژگی های جدید را مدیریت کند، امکان مقیاس پذیری آسان را فراهم می کند. این تضمین می کند که API می تواند با نیازهای برنامه رشد کند.
-
افزایش قابلیت استفاده مجدد: یک API خوب طراحی شده را می توان در چندین برنامه مورد استفاده مجدد قرار داد و باعث کاهش تکرار و ارتقای ثبات می شود. این امر توسعه را ساده می کند و در زمان و تلاش صرفه جویی می کند.
-
اسناد بهبود یافته: طرح‌های پاک را آسان‌تر می‌توان مستند کرد و به توسعه‌دهندگان نشان می‌دهد که چگونه API کار می‌کند و چگونه از آن به طور موثر استفاده کنند. این سردرگمی را کاهش می دهد و پذیرش را بهبود می بخشد.
قوانین URI
ساختار یک url به صورت زیر است
scheme :// authority / path [?query][#fragment]
برای مثال
https://soccer.api.org/teams/dortmund/players?name=Rona#2
دو نوع منابع وجود دارد
-
منابع مجموعه: شامل مجموعه ای از منابع است. می توان آن را به یک رابطه پایگاه داده تشبیه کرد
-
منابع Singleton: شامل یک منبع واحد است. می توان آن را به یک رکورد پایگاه داده تشبیه کرد.
هنگام طراحی Rest-Api
1 منابع مجموعه باید جمع باشد
+ soccer.api.org/teams/dortmond
- soccer.api.org/team/dortmond
2 منابع Singleton باید منفرد باشند و می توان آنها را با شناسه منحصربفرد که نشان دهنده منبع در سیستم پایگاه داده در پشت api است جایگزین کرد.
+soccer.api.org/teams/dortmond/players/58c1aaae-205a-11ef-aeea-a64c74618950
3 شماره اسلش های عقبی به جلو در URI شما
+soccer.api.org/teams/dortmond/players
-soccer.api.org/teams/dortmond/players/
4 استفاده کنید خط تیره بجای تاکید می کند برای بهبود خوانایی APIها
+ api.blog.com/blogs/this-is-my-blog
- api.blog.com/blogs/this_is_my_blog
5 حروف کوچک ترجیح داده می شوند حروف بزرگ در مسیرهای URI
+ api.example.com/my-api/my-resource
- api.example.com/My-Api/My-Resource
6 شماره پسوند فایل در URI ها
+ api.example.com/api/resource
- api.example.com/api/resource.json
7 نام تابع CRUD باید نه در URI ها استفاده شود
+ DELETE api.example.com/api/resource
- GET api.example.com/api.resource/delete
8 جزء پرس و جو از URI ها فقط می تواند در منابع مجموعه استفاده شود
+ GET /users?role=admin
9 جزء query یک URI باید برای صفحه بندی نتایج مجموعه استفاده شود
+ GET /users?pageSize=25&pageStartIndex=50
قوانین روش HTTP
| روش HTTP | استفاده می کند |
|---|---|
| پست | برای ایجاد یک منبع جدید. مشابه ایجاد کردن |
| گرفتن | برای دریافت نمایندگی یک منبع. شبیه به خواندن |
| قرار دادن | برای به روز رسانی یک منبع با جایگزین کردن کل منبع |
| حذف | برای حذف یک منبع |
| پچ | برای به روز رسانی یک منبع با تغییر بخشی از منبع مورد نیاز بدون جایگزینی کل منبع. |
| سر | برای دریافت پاسخ فقط سر نه بدن |
| گزینه ها | برای دریافت تمام گزینه های موجود برای یک منبع خاص |
PUT می تواند هم برای ایجاد و هم برای به روز رسانی یک منبع استفاده شود. با این حال، پیروی از بهترین شیوه‌ها، معمولاً استفاده از POST برای ایجاد منابع جدید و PUT برای جایگزینی کامل منابع موجود توصیه می‌شود.
اکنون که با این قوانین طراحی REST API مسلح شده اید، وقت آن است که آنها را عملی کنید! ایجادهای API خود را در نظرات زیر به اشتراک بگذارید و بیایید با هم دنیایی از APIهای خوش طراحی و سازگار با توسعه دهندگان بسازیم.
