یادگیری درباره ورودی‌ها و خروجی‌های رابط برنامه‌نویسی.

با راهنمایی های مستقیم و سرراست ما کار خودتون رو با رابط برنامه‌نویسی جیبرس شروع کنید.

مقدمه

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

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

مخاطبان رابط برنامه‌نویسی

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

ما برای ای‌پی‌آی‌های عمومی، سه مخاطب در ذهن داریم.

  • همکاران
  • مشتریان
  • توسعه‌دهندگان

مستندات ای‌پی‌آی با توضیحات مقدماتی درباره طراحی و تکنولوژی‌های پیاده‌سازی شروع شده است. در ادامه به دنبال اطلاعات بیشتر برای هر عملیات در نقطه پایان آن بیشتر بخوانید.

نقطه پایان

ای‌پی‌آی با ایجاد درخواست اچ‌تی‌تی‌پی‌اس به یک نشانی اینترنتی آغاز شده و متود‌های GET، POST، PUT، PATCH، HEAD و DELETE نحوه تعامل شما با اطلاعات موجود را تعیین می‌کند. تمامی آدرس‌ها تنها از طریق اچ‌تی‌تی‌پی‌اس قابل دسترسی هستند.

همه چیز (روش ها، پارامترها، و غیره) به شماره نسخه ثابت شده است، و هر ارتباط باید شامل یک نسخه باشد.

نقطه اتصال هر ای‌پی‌آی در ابتدای مستندات آن ذکر شده است

درخواست‌ها

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

متود استفاده
GET

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

مقادیر تعریف شده توسط شی جیسون می‌تواند برای ایجاد درخواست‌های اضافی استفاده شود. هر درخواستی که با استفاده از روش GET فراخوانی می‌شوند تنها خواندنی است و بر روی هیچ یک از اشیای مورد نظر تاثیر نمی گذارد.

POST

برای ایجاد یک شی جدید، درخواست شما باید با روش POST ارسال شود.

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

DELETE

برای از بین بردن یک منبع و حذف آن از حساب و ناحیه کاربری خود، باید روش DELETE استفاده شود. اگر شی مشخص شده یافت شد، حذف خواهد شد. اگر آن شی پیدا نشد، عملیات پاسخی را نشان می‌دهد که شی یافت نشد.

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

PUT

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

مانند روش DELETE، روش PUT خودکفا است. در این روش وضعیت هدف با توجه به مقادیر جدید ارائه شده و بدون در نظر گرفتن مقادیر جاری آن تنظیم می‌شوند. درخواست‌ها با استفاده از روش PUT نیازی به بررسی ویژگی‌های فعلی شی ندارند.

PATCH

برای به روز رسانی بخشی از اطلاعات مربوط به یک منبع در حسابتان، روش PATCH در دسترس است.

روش PUT و روش PATCH در نوع استفاده یکسان هستند.

HEAD

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

هدرهای پاسخ حاوی اطلاعات مفید در مورد دسترسی ای‌پی‌آی شما و نتایجی است که برای درخواست شما در دسترس هستند.

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

پاسخ‌ها

همه پاسخ‌ها در قالب جیسون قرار دارند.

  • داده‌های درخواست شده در قسمت result قرار دارند.
  • اگر شما درخواست پاسخی از سرور داشتید این پاسخ حتما در قسمت result قرار دارد.
  • ما همچنین قسمت ok و نیز آرایه‌ای از msg را در پاسخ سرور قرار می‌دهیم.
  • بعضی از پاسخ‌ها می‌توانند اطلاعات اضافی خود را در قسمت meta به شما اعلام کنند
  • هر شی از msg شامل حداقل دو قسمت type و text است

پاسخ موفقیت آمیز مثال

{ "ok": true, "result": { "abc": 123, "def": 456 } "msg": [ { "type": "info", "text": "How are you!" } ] }

پاسخ خطا مثال

{ "ok": false, "msg": [ { "type": "error", "text": "A verification code was sended to user" } ] }

کدهای پاسخ اچ‌تی‌تی‌پی

وضعیت یک پاسخ را می‌توان از کد وضعیت اچ‌تی‌تی‌پی دریافت کرد.

کد وضعیت توضیح
200 OK درخواست موفق بود
304 Not Modified درخواست موفق بود
400 Bad Request درخواست نادرست بود
401 Unauthorized کاربر دسترسی لازم را برای انجام این کار ندارد
403 Forbidden درخواست مجوز لازم را برای اجرا ندارد
404 Not Found آدرس اشتباه
429 Too many requests کاربر از محدوده مجاز عبور کرده است
405 Method Not Allowed روش اچ‌تی‌تی‌پی نادرست ارائه شده است
415 Unsupported Media Type پاسخ جیسون معتبر نیست