22 نکته طلایی برای افزایش سطح مهارت شما در طراحی API

۱۴۰۰-۵-۳ ۰۹:۴۲:۲۵  / زمان مطالعه 8 دقیقه
تا به حال با یک API کثیف و وحشتناک روبرو شدید که برای هر متنی که نوشته شده باید بازی حدس کلمه راه اندازی کنی؟ من باهاش رو برو شدم. در ادامه مقاله همراه من باشید.

تا به حال با یک API کثیف و وحشتناک روبرو شدید که برای هر متنی که نوشته شده باید بازی حدس کلمه راه اندازی کنی؟ من باهاش رو برو شدم.

تو دنیای مایکرو سرویس ها، یک طراحی سازگار برای API های شما الزامی است.

من تو این مقاله سعی میکنم بهترین روش ها رو بهتون معرفی کنم

این مقاله برگرفته و بازگردانی شده مقاله ای در Medium با همین عنوان هست.

اصطلاحات

هر طراحی API از چیزی به نام Resource Oriented Design پیروی می کند که از سه مفهوم اصلی تشکیل شده است:

منبع - Resource: یک منبع بخش از یک داده، مانند کاربر

مجموعه - Collection: به مجموعه ای از منابع مجموعه گفته می شود. مثال: لیستی از کاربران

آدرس URL: محل منبع یا مجموعه را مشخص می کند. مثال: /user

1- استفاده از kebab-case برای URL

برای مثال، اگر میخواهید لیست مرتب شده ای را بگیرید.

Bad

/systemOrders or /system_orders

Good

/system-orders

2- استفاده از camelCase در پارامتر ها

برای مثال، اگر قصد دارید لیست محصولات یک فروشگاه بخصوص را دریافت کنید.

Bad

/system-orders/{order_id} or /system-orders/{OrderId}

Good

/system-orders/{orderId}

3- استفاده از نام جمع برای اشاره به یک مجموعه

برای مثال، اگر قصد دارید اطلاعات کل کاربران را دریافت کنید.

Bad

GET /user or GET /User

Good

GET /users

4- آدرس URL با یک مجموعه شروع می شود و با یک شناسه به پایان می رسد.

اگر می خواهید مفهوم را منحصر به فرد و سازگار نگه دارید.

Bad

GET /shops/:shopId/category/:categoryId/price

Good

GET /shops/:shopId/ or GET /category/:categoryId

5- افعال را از URL منبع خود دور نگه دارید

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

Bad

POST /updateuser/{userId} or GET /getusers

Good

PUT /user/{userId}

6- از فعل ها برای URL غیر منبع استفاده کنید

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

Good

POST /alerts/245743/resend
  • نکته این که اینها عملیات CRUD ما نیستند. بلکه توابعی به حساب می آیند که کار خاصی را در سیستم ما انجام می دهند.

    7- از camelCase برای ایندکس های JSON خود استفاده کنید

    اگر سیستمی می سازید که متن درخواست یا پاسخ آن JSON باشد ، نام ایندکس باید به صورت camelCase باشد.

    Bad

    {
     user_name: "Masoud Zarjani"
     user_id: "1"
    }
    

    Good

    {
     userName: "Masoud Zarjani"
     userId: "1"
    }
    

    8- مانیتورینگ

    درخواست های HTTP شما باید یکسری نقاط پایانی رزرو داشته باشند برای نمایش اطلاعات مورد نیاز مربوط به API ها که شامل موارد زیر است:

/health

بازگرداندن کد 200 جهت بررسی صحت سرور و API

/version

بازگرداندن نسخه API در پاسخ به این نقطه پایانی

/metrics

این نقطه پایانی معیارهای مختلفی مانند زمان متوسط پاسخ را ارائه می دهد که برای اشکال زدایی و بررسی وضعیت API در بازه زمانی های مختلف بسیار کاربردی است.

نکته: این توصیه خودم هست که حتما روی پروژه جهت بررسی و مانیتور کردن عملیات های مربوط به Api و سرور(ها) از Prometheus استفاده کنید.

9- ازنام جدول برای نام منابعتون استفاده نکنید.

فقط از نام جدول به عنوان نام منبع خود استفاده نکنید. در طولانی مدت ، این نوع تنبلی می تواند مضر باشد.

Bad

product_order

Good

product-orders

10- استفاده از ابزار های طراحی API

بسیاری از ابزارهای خوب طراحی API برای مستند سازی خوب وجود دارد ، مانند:

API Blueprint

Swagger

داشتن مستندات خوب و دقیق منجر به یک تجربه کاربری عالی برای استفاده کنندگان از API شما می شود.

11- از عدد ساده به عنوان نسخه استفاده کنید

همیشه از نسخه بندی برای API استفاده کنید و آن را به سمت چپ حرکت دهید تا بیشترین دامنه را داشته باشد. شماره نسخه باید v1 ، v2 و غیره باشد.

Good

http://api.domain.com/v1/shops/3/products

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

12- تعداد کل منابع را در پاسخ قرار دهید

اگر قرار بود یک مجموعه ای از دیتا را برگردانید حتما تعداد کل آن را نیز در پاسخ بر گردانید و برای این کار می توانید از کلمه کلیدی total استفاده کنید.

Bad

{
  users: [ 
     ...
  ]
}

Good

{
  users: [ 
     ...
  ],  total: 34
}

13- پارمتر های limit و offset را بپذیرید

همیشه پارامتر های limit و offset را در درخواست هایی که با متد Get ارسال می شوند را بپذیرید.

Good

GET /shops?offset=5&limit=5

به این دلیل که برای صفحه بندی در بخش front-end نیاز است.

14- از پارمتر fields برای کوئری استفاده کنید

مقدار داده های برگشتی نیز باید در نظر گرفته شود.

یک پارامتر فیلد اضافه کنید تا فقط قسمتهای مورد نیاز از API شما مشخص شود.

مثال:

فقط نام ، آدرس و تماس مغازه ها را برگردانید.

GET /shops?fields=id,name,address,contact

همچنین به کاهش مدت زمان پاسخ در برخی از درخواست ها می انجامد.

15- در URL پارامتر token جهت احراز هویت را نگیرید

این یک عمل بسیار بد است زیرا اغلب URL ها ثبت می شوند و رمز تأیید اعتبار نیز بدون نیاز ثبت می شود.

Bad

GET /shops/123?token=some_kind_of_authenticaiton_token

Good

ارسال درخواست از Header

Authorization: Bearer xxxxxx, Extra yyyyy

همچنین مدت زمان اعتبار سنجی باید کوتاه مدت باشد.

16. نوع محتوا (Content-Type) را تأیید کنید

سرور نباید نوع محتوا را فرض کند. به عنوان مثال ، اگر برنامه / x-www-form-urlencoded را بپذیرید ، یک مهاجم می تواند یک فرم ایجاد کند و یک درخواست POST ساده را تغییر دهد.

بنابراین ، همیشه نوع محتوا را تأیید کنید و اگر می خواهید یک مورد پیش فرض داشته باشید از نوع محتوای application / json استفاده کنید.

17- از روشهای HTTP برای توابع CRUD استفاده کنید

هدف از روش های HTTP توضیح عملکرد CRUD است.

GET: دریافت اطلاعات منبع یا مجموعه

POST: ایجاد یک منبع جدید یا یک زیر منبع

PUT: بروزرسانی منبع موجود

PATCH: بروزرسانی منبع موجود با این تفاوت که فقط پارامترهای مشخص شده را تغییر می دهیم.

DELETE: حذف منبع موجود

18- از Relation در URL برای منابع تو در تو استفاده کنید

بخشی از نمونه های عملی عبارتند از:

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: افزودن فروشگاه جدید و پاسخ دادن اطلاعات مربوط به فروشگاه جدید ساخته شده

19- CORS

از سرصفحه های CORS (Cross-Origin Resource Sharing) برای همه API های روبه رو پشتیبانی کنید.

پشتیبانی از منبع مجاز CORS "*" و اعمال مجوز از طریق رمزهای معتبر OAuth را در نظر بگیرید.

از ترکیب اعتبار کاربر با اعتبار سنجی مبدا خودداری کنید.

20- امنیت

(رمزگذاری شده با TLS) HTTPS را در تمام نقاط انتهایی ، منابع و خدمات اعمال کنید.

برای همه URL های callback ، نقاط پایانی push notification و webhook ها HTTPS را اجرا کنید.

21- خطاها

خطاها یا به طور خاص خطاهای سرویس هنگامی رخ می دهد که مشتری درخواست نامعتبر یا نادرستی از سرویس می کند یا داده های نامعتبر یا نادرست را به سرویس منتقل می کند و سرویس درخواست را رد می کند.

مثالها شامل اعتبار سنجی اعتبار نامعتبر ، پارامترهای نادرست ، شناسه های نسخه ناشناخته و غیره است.

هنگام رد درخواست مشتری به دلیل یک یا چند خطای سرویس ، کدهای خطای 4xx HTTP را بازگردانید. پردازش تمام ویژگی ها و سپس بازگرداندن چندین اعتبار سنجی را در یک پاسخ در نظر بگیرید.

22- قانون طلایی

اگر در تصمیم گیری برای طراحی API خود شک دارید، این قوانین میتوانند شما را برای گرفتن تصمیم نهایی کمک کنند.

  • هموار بهتر از تو در تو است.
  • سادگی بهتر از پیچیدگی است.
  • متن ها بهتر از اعداد هستند.
  • سازگاری بهتر از سفارشی سازی است.
  • امیدوارم از مطالبی که قرار داده ام استفاده کرده باشید.
api restful برنامه نویسی