طرح API چیست؟

سلام! من به عنوان یک تأمین کننده API (ماده دارویی فعال) ، اغلب از من سؤال می کنم که یک طرح API چیست. بنابراین ، من فکر کردم که می خواهم آن را به شکلی که درک آن آسان باشد ، برای شما تجزیه کنم.

بیایید با اصول اولیه شروع کنیم. یک طرح API مانند یک طرح برای API است. این توضیحات مفصلی در مورد نحوه عملکرد API ، چه داده هایی است که انتظار دارد و چه داده هایی باز می گردد. به عنوان مجموعه ای از قوانین و دستورالعمل ها فکر کنید که هم ارائه دهنده API (این من هستم!) و هم مصرف کننده API (این شما یا تیم خود هستید) برای اطمینان از ارتباط صاف و کارآمد باید دنبال کنید.

چرا یک طرح API مهم است؟

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

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

چه چیزی در یک طرح API وجود دارد؟

یک طرح API به طور معمول شامل مؤلفه های زیر است:

1. نقاط پایانی

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

2. فرمت های درخواست و پاسخ

این طرح فرمت داده هایی را که برای ارسال درخواست های خود (به عنوان مثال ، JSON ، XML) و قالب داده هایی که API در پاسخ های خود باز می گرداند ، تعریف می کند. این تضمین می کند که هم ارائه دهنده API و هم مصرف کننده هنگام استفاده از داده ها در همان صفحه قرار دارند.

3. پارامترها

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

4. رسیدگی به خطا

این طرح همچنین توضیح می دهد که چگونه API خطاها را برطرف می کند. این کدهای خطایی را که API ممکن است برگرداند و هر کد به چه معنی است ، تعریف می کند. این به توسعه دهندگان کمک می کند تا درک کنند که در هنگام بروز خطا و نحوه رفع آن چه اشتباهی رخ داده است.

انواع طرح های API

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

مشخصات OpenAPI (OAS)

این یکی از محبوب ترین استانداردها برای مستند سازی API های استراحت است. از یک فایل YAML یا JSON برای توصیف نقاط پایانی API ، قالب های درخواست و پاسخ ، پارامترها و موارد دیگر استفاده می کند. OAS به طور گسترده ای توسط ابزارها و چارچوب ها پشتیبانی می شود و تولید اسناد ، SDK ها و موارد آزمایش را آسان می کند.

طرح گرافیک

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

بافر پروتکل

بافرهای پروتکل (ProtoBUF) یک قالب سریال سازی باینری زبان-آگنوستیک است که توسط Google ساخته شده است. از یک فایل طرحواره برای تعریف ساختار داده هایی که سریالی شده و دفع می شوند استفاده می کند. Protobuf به دلیل عملکرد بالا و اندازه پیام کوچک شناخته شده است و آن را به عنوان یک انتخاب محبوب برای API ها که نیاز به رسیدگی به مقادیر زیادی از داده ها دارند ، ایجاد می کند.

چگونه از طرح های API به عنوان تأمین کننده API استفاده می کنیم

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

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

علاوه بر این ، ما از طرح های API برای تولید SDK و موارد آزمایش استفاده می کنیم. با استفاده از ابزارهایی که از مشخصات OpenAPI پشتیبانی می کنند ، می توانیم به طور خودکار کد را در زبانهای مختلف برنامه نویسی تولید کنیم ، که باعث می شود API های ما در برنامه های خود ادغام کنیم. ما همچنین از این طرح برای تولید موارد آزمایش استفاده می کنیم ، که به ما کمک می کند تا اطمینان حاصل کنیم که API های ما به درستی کار می کنند و آنها نیازهای مشتریان را برآورده می کنند.

نمونه های دنیای واقعی

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

مثال 1: استفاده از API ما برای کسب اطلاعات در موردThioxanthen-9-One CAS با کیفیت بالا: 492-22-8

فرض کنید شما یک محقق هستید که به دنبال کسب اطلاعات در مورد یک ترکیب شیمیایی خاص هستید. شما می توانید از API ما برای دسترسی به داده هایی مانند خصوصیات ترکیب ، روش های سنتز و اطلاعات ایمنی استفاده کنید. طرح API دقیقاً به شما می گوید که چه نقطه پایانی را فراخوانی می کنید ، چه پارامترهایی را برای عبور (به عنوان مثال ، شماره CAS) و پاسخ در چه قالب ای قرار می گیرد.

در اینجا نمونه ای از درخواست API ما با استفاده از CURL آورده شده است:

curl -x دریافت "https://api.oursite.com/compounds/492-22-8" -h "قبول: برنامه/json"

پاسخ ممکن است چیزی شبیه به این باشد:

{"نام": "thioxanthen-9-one" ، "cas_number": "492-22-8" ، "مولکولی_ وزنه": 212.26 ، "خواص": {"ذوب_ نقطه": "85-87 ° C" ، "جوشکاری_ نقطه": "365.7 ° C در 760 mmhg" با y در حضور z ... "،" روش 2: از شرایط واکنش زیر استفاده کنید ... "]}

مثال 2: ایجاد سفارش جدید برایCAS No.455943-61-0 عرضه بزرگ

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

در اینجا نمونه ای از درخواست API ما با استفاده از پایتون آورده شده است:

درخواست های واردات url = "https://api.oursite.com/orders" داده = {"product_id": "455943-61-0" ، "مقدار": 1000 ، "تحویل_دد": "123 خیابان اصلی ، USAA" {headers = {"" محتوای-نوع ":" هدر = هدر) چاپ (پاسخ. json ())

پاسخ ممکن است چیزی شبیه به این باشد:

{"order_id": "123456" ، "پیام": "سفارش با موفقیت ایجاد شده است. سفارش شما ظرف 24 ساعت پردازش می شود." }

پایان

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

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

منابع

• Fielding ، RT (2000). سبک های معماری و طراحی معماری های نرم افزاری مبتنی بر شبکه. دانشگاه کالیفرنیا ، ایروین.
• Khare ، R. ، & Frystyk ، H. (1997). پروتکل انتقال HyperText - HTTP/1.1. RFC 2068.
• Lindley ، S. ، & Miller ، B. (2015). GraphQL: یک زبان پرس و جو داده. فیس بوک.
• Varda ، A. (2008). بافرهای پروتکل: قالب مبادله داده Google. وبلاگ منبع باز گوگل.