بهترین شیوه های طراحی در API

نکاتی برای ایجاد API ساختار یافته و حفظ شده

در Ayrshare ، ما همچنان به مشاهده رابط های برنامه (API) ، که به عنوان ستون فقرات برای برقراری ارتباط صاف بین سیستم های نرم افزاری مختلف پذیرفته شده است. و دقیقاً مانند یک شوخی خوب (پدر) ، API باید به راحتی قابل درک باشد و یک برداشت ماندگار را به جا بگذارد. شما نمی خواهید توسعه دهندگان سر خود را خراش دهند و بگویند “من آن را نمی فهمم!” -“من از راه خارج شده ام.”

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

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

مخاطبان توسعه دهنده خود را درک کنید

قبل از نوشتن یک ردیف کد ، ضروری است بدانید چه کسی از API شما استفاده خواهد کردآیا توسعه دهندگان یا تازه واردان جعل شده اند؟ درک مخاطبان هدف شما بر تصمیمات مربوط به پیچیدگی ، سبک مستندات و سطح انتزاع تأثیر می گذارد. مورد شخصی خود را در مورد استفاده-آنچه را که هنگام خواندن اسناد API شرکت به دنبال آن هستید ، در نظر بگیرید. نوار

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

توالی و استانداردها را تعیین کنید

قوام برای طراحی API مهم است. آیا می خواهید از استانداردهای مختلف تار شوید ، مانند برخی از پاسخ های API از یک مورد (شتر) و سایر موارد مار (Snake_case) استفاده می کند؟ و برای همان داده ها ، از نام فیلدهای مختلف مانند Age و User_age استفاده می شود؟ یوک

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

هنگام ایجاد دنباله ای از API و استانداردها ، روی:

• روش های HTTP: با استفاده از روشهای HTTP به طور مناسب به اصول آرامش بخش بچسبید:
  • GET برای استخراج منابع
  • POST برای ایجاد منابع
  • PUT یا PATCH برای به روزرسانی منابع
  • DELETE برای حذف منابع
• پاسخ نام فیلد: اگر جواب یک نقطه پایان باشد userIdاستفاده نکنید id در پاسخ دیگر به نقطه پایان اگر آنها همان مقدار باشند.
• قالبهای داده: برای اطمینان از سازگاری و تطبیق پذیری ، به قالب های داده استاندارد مانند زمان زولو بچسبید.
• ساختار URL در نقطه پایان: به عنوان مثال ، فلسفه های API در مورد نحوه ساخت URL نقطه پایان وجود دارد GET https://api.ayrshare.com/api/analyticsدر این مثال ، عمل است GET و نوع است analyticsواقعاً مهم نیست که آیا این سبک شما در برابر است GET https://api.ayrshare.com/api/getAnalyticsl نکته مهم این است که در تمام نقاط پایانی سازگار باشد.
• کدهای پاسخ HTTP: کد پاسخ HTTP اولین نشانگر کاربر API است که تماس موفقیت آمیز بوده است یا در صورت بروز مشکل. به عنوان مثال ، پاسخ در محدوده 200 به این معنی است که همه چیز خوب است. پاسخ 400 یا بالاتر در اینجا مشکلی بود.

مثالها:

یک نشریه ایجاد کنید: برای ایجاد یک انتشار جدید در رسانه های اجتماعی ، Ayrshare از آن استفاده می کند POST روش با /post نکته نهایی:

  POST https://api.ayrshare.com/api/post

مرجع درخواست:

  {
    "post": "Hello World!",
    "platforms": ["facebook"]
  }

بدن برای پاسخ:

{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "1835773643315433893",
            "postUrl": "https://www.facebook.com/33892",
            "platform": "facebook"
        }
    ],
    "id": "G5y3PRI7bzLq1GmV5Xaa",
    "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc092",
    "post": "A beautiful day",
    "validate": true
}

در نظر بگیرید همیشه بازگشت statusبه عنوان "error" یا "success" و مطمئن باشید که با کد پاسخ HTTP مطابقت دارد.

انتشار یک نشریه: برای به دست آوردن جزئیات یک پست خاص استفاده کنید GET روش با /post/{id} نکته نهایی:

  GET https://app.ayrshare.com/api/post/1234567890

این استفاده مداوم از روش ها و ساختارهای HTTP نقطه انتهایی باعث می شود API بصری و استفاده آسان شود.

طراحی با مقیاس در ذهن

با افزایش API شما ، باید بدون تخریب بهره وری ، بار افزایش یابد.

• غیر طبیعی: API خود را طراحی کنید تا بدون شهروندی باشد. هر درخواست باید شامل تمام اطلاعات مورد نیاز برای پردازش آن باشد ، که این امکان را برای مقیاس بهتر فراهم می کند. هر درخواست Ayrshare API شامل کلیه اطلاعات لازم ، مانند کلید و پارامترهای API ، اطمینان حاصل می کند که سرور نیازی به ذخیره اطلاعات در مورد جلسه بین درخواست ها ندارد.
• مدیریت منابع مؤثر: نقاط انتهایی خود را بهینه کنید تا به طور مؤثر چندین عملیات را پردازش کنید. اگر همه چیز خوب پیش برود ، تماس های API زیادی دریافت خواهید کرد و باید بتوانید از همه آنها پشتیبانی کنید. زیرساخت ها را بدون سرور – مانند Supabase یا Firebase – در نظر بگیرید تا به طور خودکار با افزایش بار مقابله کنید ، اما هشدار داده می شود که به طور خودکار می تواند گران باشد ، بنابراین حتما محدودیت های بودجه را تعیین کنید.
• تعادل بار و سرعت محدود کننده: برای انتشار بار و جلوگیری از سوءاستفاده از راهکارهایی استفاده کنید. به منظور حفظ نتایج بهینه و جلوگیری از سوءاستفاده ، Ayrshare محدودیت در استفاده از عادلانه که در اسناد ما به تفصیل انجام شده است ، برای ارائه استفاده منصفانه در بین همه مشتریان متوجه می شود. بازگشت 429 اگر خطایی در محدودیت سرعت وجود داشته باشد ، کد پاسخ HTTP.
• عملیات انبوه: Ayrshare به شما امکان می دهد با یک درخواست ، یک پست را به چندین سیستم عامل رسانه های اجتماعی ارسال کنید و تعداد تماس های API را کاهش می دهد. این برای کاربر و سیستم شما مفید است.

{
   "post": "Exciting news! Our app just got better.",
   "platforms": ["twitter", "facebook", "linkedin", "instagram"]
}

اجرای یک سیاست استهلاک روشن

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

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

هنگامی که ما قصد داریم نقطه پایان یا عملکرد را در Ayrshare لغو کنیم ، آن را توسط:

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

با تمرکز بر روی یک سیاست عقب نشینی پایدار ، Ayrshare حتی در هنگام معرفی ویژگی ها و پیشرفت های جدید ، یک محیط API پایدار و قابل اعتماد را حفظ می کند.

اقدامات امنیتی را در اولویت قرار دهید

محافظت از داده ها و تضمین ارتباط ایمن مذاکره نمی شود. شبکه

صدور گواهینامه و مجوز: اجرای مکانیسم های احراز هویت پایدار مانند کلیدهای API یا OAUTH 2.0. Ayrshare از کلیدهای API برای تأیید اعتبار استفاده می کند. کلید API خود را وارد کنید Authorization عنوان:

  Authorization: Bearer YOUR_API_KEY

https همه جا: https را برای رمزگذاری داده ها در ترانزیت پر کنید. نقاط پایانی Ayrshare به HTTP نیاز دارند ، و اطمینان حاصل می کنند که تمام داده های منتقل شده رمزگذاری شده اند.

آزمایش امنیتی: یک قلم معمولی (آزمایش نفوذ) را روی API خود انجام دهید. اگر سعی در شکستن آنها ندارید ، شخص دیگری این کار را خواهد کرد.

مستندات واضح و جامع را ارائه دهید

مستندات خوب به اندازه خود API مهم است.

مرجع API: اطلاعات دقیق در مورد هر نقطه پایان ، نمونه هایی از پارامترها ، درخواست و پاسخ ضروری است. اطلاعات زیادی خوب است تا زمانی که سازماندهی شود. در اینجا مثالی از پست پست ما آورده شده است:

دروس و راهنما: یک راهنمای مرحله ای برای کارهای عمومی برای کمک به توسعه دهندگان سریع شروع کنید. یک درس مکتوب عالی است ، اما یک آموزش ویدیویی باعث درخشش شما خواهد شد! به عنوان مثال ، در اینجا راهنمای ادغام ما است:

نمونه کد: نمونه هایی از زبان های برنامه نویسی متعدد. AI امروز برای ترجمه یک زبان برنامه نویسی به دیگری بسیار عالی است ، اما مردم هنوز دوست دارند نمونه هایی از زبان مورد نظر خود را ببینند و این کار را نیز انجام دهند. به عنوان مثال:

پردازش خطاهای پایدار را اعمال کنید

کمک های واضح و مداوم در پردازش خطاها در ایجاد خطا و بهبود تجربه توسعه دهندگان.

• کدهای وضعیت استاندارد HTTP: از کدهای وضعیت مناسب برای نشان دادن نتیجه تماس API استفاده کنید. لطفا ببینید که در مورد این مورد بحث شده است.
• طراحی پیام خطاها: پیام های معنی دار از خطاها و کدها را ارائه دهید که به شناسایی و حل مشکلات کمک می کند.
• ساختار شیء: یک ساختار پاسخ دهنده خطای مداوم را حفظ کنید.

به عنوان مثال ، در اینجا خطای حذف پستی است که در آن ارسال شده ارسال شده از یک پست یافت نشد:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "action": "delete",
    "status": "error",
    "code": 114,
    "message": "Delete id not found.",
    "id": "IdpUOyihLEpIx0d0N9mI" 
}

تست و نظارت آسان را تسهیل کنید

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

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

در Ayrshare ، ما اهمیت یک طراحی API پایدار را درک می کنیم. API رسانه های اجتماعی ما با این بهترین شیوه ها ساخته شده است و یک ادغام بدون دردسر و تجربه عالی توسعه دهندگان را تضمین می کند.