تا به حال با یک API کثیف و وحشتناک روبرو شدید که برای هر متنی که نوشته شده باید بازی حدس کلمه راه اندازی کنی؟ من باهاش رو برو شدم.
تو دنیای مایکرو سرویس ها، یک طراحی سازگار برای API های شما الزامی است.
من تو این مقاله سعی میکنم بهترین روش ها رو بهتون معرفی کنم
این مقاله برگرفته و بازگردانی شده مقاله ای در Medium با همین عنوان هست.
هر طراحی API از چیزی به نام Resource Oriented Design پیروی می کند که از سه مفهوم اصلی تشکیل شده است:
منبع - Resource: یک منبع بخش از یک داده، مانند کاربر
مجموعه - Collection: به مجموعه ای از منابع مجموعه گفته می شود. مثال: لیستی از کاربران
آدرس URL: محل منبع یا مجموعه را مشخص می کند. مثال: /user
برای مثال، اگر میخواهید لیست مرتب شده ای را بگیرید.
/systemOrders or /system_orders
/system-orders
برای مثال، اگر قصد دارید لیست محصولات یک فروشگاه بخصوص را دریافت کنید.
/system-orders/{order_id} or /system-orders/{OrderId}
/system-orders/{orderId}
برای مثال، اگر قصد دارید اطلاعات کل کاربران را دریافت کنید.
GET /user or GET /User
GET /users
اگر می خواهید مفهوم را منحصر به فرد و سازگار نگه دارید.
GET /shops/:shopId/category/:categoryId/price
GET /shops/:shopId/ or GET /category/:categoryId
برای بیان قصد خود در URL از افعال استفاده نکنید. در عوض، از روشهای مناسب HTTP برای مشخص نمودن عملیات استفاده کنید.
POST /updateuser/{userId} or GET /getusers
PUT /user/{userId}
شما یک نقطه پایانی دارید که به جز یک عمل چیزی بر نمی گرداند. در این حالت می توانید از افعال استفاده کنید. به عنوان مثال ، اگر می خواهید هشدار را برای یک کاربر دوباره ارسال کنید.
POST /alerts/245743/resend
* نکته این که اینها عملیات CRUD ما نیستند. بلکه توابعی به حساب می آیند که کار خاصی را در سیستم ما انجام می دهند.
اگر سیستمی می سازید که متن درخواست یا پاسخ آن JSON باشد ، نام ایندکس باید به صورت camelCase باشد.
{ user_name: "Mohammad Faisal" user_id: "1" }
{ userName: "Mohammad Faisal" userId: "1" }
درخواست های HTTP شما باید یکسری نقاط پایانی رزرو داشته باشند برای نمایش اطلاعات مورد نیاز مربوط به API ها که شامل موارد زیر است:
/health
بازگرداندن کد 200 جهت بررسی صحت سرور و API
/version
بازگرداندن نسخه API در پاسخ به این نقطه پایانی
/metrics
این نقطه پایانی معیارهای مختلفی مانند زمان متوسط پاسخ را ارائه می دهد که برای اشکال زدایی و بررسی وضعیت API در بازه زمانی های مختلف بسیار کاربردی است.
نکته این توصیه خودم هست که حتما روی پروژه جهت بررسی و مانیتور کردن عملیات های مربوط به Api و سرور(ها) از Prometheus استفاده کنید.
فقط از نام جدول به عنوان نام منبع خود استفاده نکنید. در طولانی مدت ، این نوع تنبلی می تواند مضر باشد.
product_order
product-orders
بسیاری از ابزارهای خوب طراحی API برای مستند سازی خوب وجود دارد ، مانند:
داشتن مستندات خوب و دقیق منجر به یک تجربه کاربری عالی برای استفاده کنندگان از API شما می شود.
همیشه از نسخه بندی برای API استفاده کنید و آن را به سمت چپ حرکت دهید تا بیشترین دامنه را داشته باشد. شماره نسخه باید v1 ، v2 و غیره باشد.
http://api.domain.com/v1/shops/3/products
همیشه از نسخه دهی در API خود استفاده کنید چون اگر API توسط بخش های خارجی استفاده می شود، تغییر نقطه پایان می تواند عملکرد آنها را متزلزل کند.
اگر قرار بود یک مجموعه ای از دیتا را برگردانید حتما تعداد کل آن را نیز در پاسخ بر گردانید و برای این کار می توانید از کلمه کلیدی total استفاده کنید.
{ users: [ ... ] }
{ users: [ ... ], total: 34 }
همیشه پارامتر های limit و offset را در درخواست هایی که با متد Get ارسال می شوند را بپذیرید.
GET /shops?offset=5&limit=5
به این دلیل که برای صفحه بندی در بخش front-end نیاز است.
مقدار داده های برگشتی نیز باید در نظر گرفته شود.
یک پارامتر فیلد اضافه کنید تا فقط قسمتهای مورد نیاز از API شما مشخص شود.
مثال:
فقط نام ، آدرس و تماس مغازه ها را برگردانید.
GET /shops?fields=id,name,address,contact
همچنین به کاهش مدت زمان پاسخ در برخی از درخواست ها می انجامد.
این یک عمل بسیار بد است زیرا اغلب URL ها ثبت می شوند و رمز تأیید اعتبار نیز بدون نیاز ثبت می شود.
GET /shops/123?token=some_kind_of_authenticaiton_token
ارسال درخواست از Header
Authorization: Bearer xxxxxx, Extra yyyyy
همچنین مدت زمان اعتبار سنجی باید کوتاه مدت باشد.
سرور نباید نوع محتوا را فرض کند. به عنوان مثال ، اگر برنامه / x-www-form-urlencoded را بپذیرید ، یک مهاجم می تواند یک فرم ایجاد کند و یک درخواست POST ساده را تغییر دهد.
بنابراین ، همیشه نوع محتوا را تأیید کنید و اگر می خواهید یک مورد پیش فرض داشته باشید از نوع محتوای application / json استفاده کنید.
هدف از روش های HTTP توضیح عملکرد CRUD است.
بخشی از نمونه های عملی عبارتند از:
GET /shops/2/products : لیست تمامی محصولات را از فروشگاه 2 دریافت کنGET /shops/2/products/31: جزئیات محصول 31 را که متعلق به فروشگاه 2 است ، دریافت کنDELETE /shops/2/products/31: محصول 31 که متعلق به فروشگاه 2 است را حذف کنPUT /shops/2/products/31: باید اطلاعات محصول 31 از فروشگاه 2 را بروزرسانی کندPOST /shops: افزودن فروشگاه جدید و پاسخ دادن اطلاعات مربوط به فروشگاه جدید ساخته شدهاز سرصفحه های CORS (Cross-Origin Resource Sharing) برای همه API های روبه رو پشتیبانی کنید.
پشتیبانی از منبع مجاز CORS "*" و اعمال مجوز از طریق رمزهای معتبر OAuth را در نظر بگیرید.
از ترکیب اعتبار کاربر با اعتبار سنجی مبدا خودداری کنید.
(رمزگذاری شده با TLS) HTTPS را در تمام نقاط انتهایی ، منابع و خدمات اعمال کنید.
برای همه URL های callback ، نقاط پایانی push notification و webhook ها HTTPS را اجرا کنید.
خطاها یا به طور خاص خطاهای سرویس هنگامی رخ می دهد که مشتری درخواست نامعتبر یا نادرستی از سرویس می کند یا داده های نامعتبر یا نادرست را به سرویس منتقل می کند و سرویس درخواست را رد می کند.
مثالها شامل اعتبار سنجی اعتبار نامعتبر ، پارامترهای نادرست ، شناسه های نسخه ناشناخته و غیره است.
22- قانون طلایی
اگر در تصمیم گیری برای طراحی API خود شک دارید، این قوانین میتوانند شما را برای گرفتن تصمیم نهایی کمک کنند.
امیدوارم از مطالبی که قرار داده ام استفاده کرده باشید.
منبع: وبلاگ شخصی خودم
روز خوش
