شروع کار با API Instatus
همه نقاط پایانی زیر نشانی https://api.instatus.com هستند. آنها عموماً از معماری REST پیروی میکنند.
همه درخواستها باید با هدر Content-Type: application/json بهصورت JSON کدگذاری شوند.
پاسخهای API Instatus، از جمله خطاها، نیز بهصورت JSON کدگذاری میشوند.
احرازهویت
درخواستها به API Instatus باید یک کلید API را از طریق هدر Authorization ارسال کنند:
Authorization: Bearer <API_KEY>
کلیدها را در داشبورد ← توسعهدهنده با ساخت کلید بسازید. میتوانید چند کلید داشته باشید که هر کدام نام خودش را دارد، مثلاً «GitHub Actions» یا «Terraform». کلیدها با inst_sk_ شروع میشوند.
هر کلید چه کاری میتواند بکند
هر کلید تنظیمات خودش را دارد:
- نقش: عضو، ویرایشگر، یا یک نقش سفارشی در طرح Business. نقش تعیین میکند کلید چه چیزهایی را میتواند ببیند و تغییر دهد، درست همانطور که برای افراد تعیین میکند. کلیدها نمیتوانند مالک باشند، پس صورتحساب، نقشها و حذف کردن در دست افراد میماند.
- دسترسی: مشاهده و تغییر یا فقط مشاهده. کلید فقط مشاهده نمیتواند هیچ چیزی را تغییر دهد، هر چه نقشش اجازه بدهد.
- پروژهها: همه پروژهها، از جمله پروژههایی که بعداً اضافه میکنید، یا فقط پروژههایی که انتخاب میکنید.
- انقضا: تاریخی که کلید از کار میافتد. در طرح Free یک کلید حداکثر 90 روز معتبر میماند، در Pro حداکثر 1 سال، و در Business و Enterprise هر مدتی که بخواهید، حتی بدون انقضا. مالک تیم میتواند در تنظیمات تیم ← کلیدهای API محدودیت کوتاهتری بگذارد. کلیدهایی که پیش از تنظیمات کلید ساخته شدهاند تغییری نمیکنند، و کلیدهای موجود با تغییر طرح، تاریخ خود را حفظ میکنند.
- IPهای مجاز: در طرح Business، کلید فقط از نشانیها یا بازههای IP که فهرست میکنید کار میکند.
هر کلید یا متعلق به تیم است یا متعلق به شما:
- کلیدهای تیم وقتی سازندهشان تیم را ترک کند همچنان کار میکنند. از آنها برای CI، اسکریپتها و یکپارچهسازیها استفاده کنید.
- کلیدهای شخصی بهجای شما عمل میکنند و هرگز بیش از شما کاری نمیکنند. میتوانند مثل خودتان را بهعنوان نقش داشته باشند و اگر تیم را ترک کنید از کار میافتند.
مالکان تیم قوانین کلیدها را در تنظیمات تیم ← کلیدهای API تعیین میکنند: بیشترین مدتی که یک کلید میتواند معتبر بماند، اینکه اعضا میتوانند کلید تیم بسازند یا نه، و اینکه کلیدهای شخصی مجاز هستند یا نه.
ساختن، تغییر دادن، چرخش و لغو یک کلید در فعالیت تیم نشان داده میشود، و همینطور کلیدی که به دلیل افشا شدن لغو شده است. هر کاری که از طریق یک کلید یا یک برنامهٔ متصل انجام شود، آنجا بهصورت شخص از طریق نام کلید یا برنامه نمایش داده میشود.
امن نگه داشتن کلیدها
- هر کلید فقط یک بار، هنگام ساخت، نمایش داده میشود. همان موقع کپیاش کنید و مانند یک راز نگهش دارید.
- برای جایگزین کردن یک کلید، آن را باز کنید و روی چرخش کلیک کنید. انتخاب کنید کلید قدیمی تا چه مدت، حداکثر 7 روز، کار کند تا فرصت داشته باشید هر چیزی را که از آن استفاده میکند بهروز کنید.
- کلید را از منوی آن لغو کنید تا بیدرنگ از کار بیفتد.
کلیدهایی که پیش از تنظیمات کلید ساخته شدهاند بدون تغییر کار میکنند. این کلیدها در بخش توسعهدهنده با برچسب «ساختهشده پیش از تنظیمات کلید» نشان داده میشوند و آنجا میتوانید برایشان محدودیت بگذارید یا با کلید جدید جایگزینشان کنید.
خطاهای کلید
وقتی کلیدی نتواند درخواستی انجام دهد، خطا یکی از این کدها را دارد و پیام آن میگوید چه چیزی را باید تغییر دهید.
| کد | وضعیت | علت |
|---|---|---|
invalid_key | 401 | این کلید وجود ندارد. بررسی کنید که همه آن را کپی کرده باشید. |
key_expired | 401 | تاریخ انقضای کلید گذشته است. |
key_revoked | 401 | کلید لغو شده است. |
key_owner_left | 401 | فردی که کلید شخصی بهجای او عمل میکند تیم را ترک کرده است. |
key_view_only | 403 | کلید فقط مشاهده است و درخواست چیزی را تغییر میدهد. |
role_not_allowed | 403 | نقش کلید اجازه مشاهده یا تغییر این مورد را نمیدهد. |
ip_not_allowed | 403 | درخواست از نشانی IPای آمده که کلید اجازه نمیدهد. |
page_not_allowed | 403 | کلید نمیتواند از این پروژه استفاده کند. |
account_action_not_allowed | 403 | کلیدها نمیتوانند صفحه، تیم یا فضای کاری بسازند یا حذف کنند. از داشبورد استفاده کنید. |
route_not_allowed | 403 | این مسیر جزو API مستند نیست. |
دریافت شناسه صفحه شما
شناسه صفحه شما را میتوان با این گامها در داشبورد پیدا کرد: ۱. به داشبورد خود بروید. ۲. روی پروژهتان در گوشه بالا-سمت چپ راستکلیک کنید تا منو باز شود. ۳. روی Copy Project ID کلیک کنید تا شناسه صفحهتان در حافظه کپی شود.

خطاها
همه نقاط پایانی API در پاسخهای خطا یک code و message دارند.
{"error": {"code": "forbidden","message": "Not authorized"}}
مقادیر وضعیت
وضعیتهای ممکن صفحه. این همان status ریزدانهای است که API فعلی (نسخه ۲ و بالاتر) برمیگرداند. نقطه پایانی قدیمی summary.json و اعلانهای وبهوک از شکلی فشرده با تنها UP، HASISSUES و UNDERMAINTENANCE استفاده میکنند.
UPHASISSUESALLUNDERMAINTENANCEALLDEGRADEDPERFORMANCEALLPARTIALOUTAGEALLMINOROUTAGEALLMAJOROUTAGESOMEUNDERMAINTENANCESOMEDEGRADEDPERFORMANCESOMEPARTIALOUTAGESOMEMINOROUTAGESOMEMAJOROUTAGEONEUNDERMAINTENANCEONEDEGRADEDPERFORMANCEONEPARTIALOUTAGEONEMINOROUTAGEONEMAJOROUTAGE
وضعیتهای ممکن جزء:
OPERATIONALUNDERMAINTENANCEDEGRADEDPERFORMANCEPARTIALOUTAGEMAJOROUTAGE
وضعیتهای ممکن حادثه:
INVESTIGATINGIDENTIFIEDMONITORINGRESOLVED
وضعیتهای ممکن تعمیرات:
NOTSTARTEDYETINPROGRESSCOMPLETED