مرجعپیش‌نمایش

مرجع API

نردبون را با همان API که داشبورد از آن استفاده می‌کند خودکار کنید.

داشبورد روی API عمومی نردبون ساخته شده است: هر کاری که در داشبورد انجام می‌دهید از همان endpointهایی می‌گذرد که خودتان هم می‌توانید فراخوانی کنید. با این API می‌توانید کارهای سازمانتان را از اسکریپت‌ها، pipelineهای CI و ابزارهای خودتان خودکار کنید. نردبون یک API مدیریتی و یک API داخلی جداگانه هم دارد، اما این دو عمومی نیستند.

نسخه‌ها و مستندات

همه‌ی endpointها زیر یک مسیر نسخه‌دار قرار دارند: /api/v1/.
مستندات تعاملی OpenAPI در /api/docs/ روی میزبان API در دسترس است. این مستندات همه‌ی endpointها و scopeی را که هر کدام لازم دارد فهرست می‌کند و می‌توانید درخواست‌ها را همان‌جا امتحان کنید.

احراز هویت

روش	کاربرد
نشست (session)	داشبورد. وقتی وارد حسابتان می‌شوید (با MFA یا SSO، اگر از آن‌ها استفاده می‌کنید)، یک نشست ساخته می‌شود.
کلید API	اسکریپت‌ها و ابزارها. هر کلید به نام شما یا به نام یک حساب سرویس کار می‌کند و از یک روز تا یک سال، یا تا وقتی باطلش کنید، اعتبار دارد.
حساب سرویس	خودکارسازی‌ای که نباید به یک شخص وابسته باشد. عضوی است که آدم نیست: نقش دارد، جای عضو را نمی‌گیرد، هیچ‌وقت وارد نمی‌شود و با رفتن آدم‌ها از کار نمی‌افتد.
OAuth client	ابزارهایی که OAuth 2.0 را می‌شناسند، مثل Terraform. هر OAuth client مال یک حساب سرویس است و با رمزش یک توکن دسترسی می‌گیرد که یک ساعت اعتبار دارد.

هر کلید API و OAuth client چند scope دارد: اینکه در هر بخش چه کاری بکند، فقط خواندن یا تغییر هم. هر کدام فقط کاری را می‌کند که هم scopeهایش و هم نقشِ کسی که به نامش کار می‌کند اجازه بدهد؛ پس پایین آوردن نقش یک حساب سرویس، دسترسی همه‌ی کلیدهایش را یک‌جا کم می‌کند.

کارهایی که هیچ credentialی نمی‌تواند انجام دهد

هیچ کلید API یا توکن OAuth، با هر scope که داشته باشد، نمی‌تواند credential بسازد، حساب سرویس را مدیریت کند یا پولی جابه‌جا کند. credentialی که لو برود نه می‌تواند برای خودش credential تازه بسازد و نه از کیف پول سازمانتان خرج کند.

کلید API را به‌عنوان bearer token بفرستید:

curl -H "Authorization: Bearer nbapi-…" \
  https://app.nardeboon.io/api/v1/orgs/<org>/networks

OAuth client توکنش را با روش client credentials می‌گیرد و بعد همین‌طور از آن استفاده می‌کند:

curl -u "nbcl-…:nbcs-…" -d grant_type=client_credentials \
  https://app.nardeboon.io/api/v1/oauth/token
# {"access_token": "nbat-…", "token_type": "Bearer", "expires_in": 3600, "scope": "…"}

با -d scope="devices:read" می‌توانید scopeهای کمتری از آنچه client دارد بخواهید. دستگاه‌هایی که یک حساب سرویس اضافه می‌کند باید تگ داشته باشند، چون مال شبکه‌اند نه مال یک شخص.

Webhookها

Webhookها رویدادهای گزارش رویدادهای سازمانتان را به آدرسی که شما تعیین می‌کنید می‌فرستند؛ پس سیستم‌هایتان بدون اینکه مدام API را بررسی کنند، می‌توانند به تغییرها واکنش نشان دهند. بخش‌هایی را که می‌خواهید انتخاب کنید (دستگاه‌ها، شبکه‌ها و قوانین، اعضا، صورت‌حساب، کلیدهای API، سازمان) یا همه را. endpoint باید HTTPS عمومی باشد و هر پاسخ 2xx یعنی رسید؛ هر پاسخ دیگری حدود نه ساعت دوباره امتحان می‌شود.

هر ارسال امضا دارد. پیش از اینکه به یک ارسال اعتماد کنید، هدر Nardeboon-Signature را بررسی کنید:

Nardeboon-Signature: t=<unix time>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>

HMAC زمان، یک نقطه و بدنه‌ی خام را با کلید امضای webhookتان حساب کنید، در زمان ثابت مقایسه کنید و زمان‌هایی را که بیش از چند دقیقه گذشته‌اند رد کنید.

مثال: قیمت‌های عمومی

GET /api/v1/pricing عمومی است و به احراز هویت نیاز ندارد. این endpoint قیمت‌های عمومی نردبون را برمی‌گرداند:

GET /api/v1/pricing

API یا CLI؟

با API می‌توانید سازمانتان را از هر جایی مدیریت کنید. CLI دستگاهی را مدیریت می‌کند که رویش اجرا می‌شود و خروجی --json آن برای اسکریپت‌های همان دستگاه مناسب است.