API

API عمومی ابران با /v1 شروع می‌شود و قرارداد ماشین‌خوان آن از OpenAPI تولید می‌شود. frontend، CLI و SDK باید همین قرارداد را مصرف کنند.

احراز هویت و پروژه

Browser session و bearer token بر اساس قابلیت endpoint پشتیبانی می‌شوند. مسیرهای collection پروژه‌ای از X-Project-ID استفاده می‌کنند و مسیرهای item مالکیت پروژه را از خود resource resolve می‌کنند.

شکل پاسخ‌ها

یک resource به شکل object مستقیم برمی‌گردد. لیست‌های صفحه‌بندی‌شده از شکل زیر استفاده می‌کنند:

{
  "items": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}

acknowledgement خالص با 204 No Content پاسخ داده می‌شود.

خطاها

خطاها باید envelope پایدار با code، message و field details اختیاری داشته باشند. client نباید متن داخلی Kubernetes، SQL، provider یا credential را parse کند.

تغییر قرارداد

تغییرات public API باید در OpenAPI ثبت شوند و بعد از آن SDK و مصرف‌کننده‌ها به‌روزرسانی شوند.