Spitfirev0.62.2 · Yenilikler

Sürüm: 0.62.2Bu dokümantasyon Spitfire 0.62.2 içindir.

API referansı

Bu sayfa, Spitfire'ın kendi HTTP API'sini kendi betiklerinizden ve araçlarınızdan nasıl kullanacağınızı anlatır: kimlik doğrulama, çalışma alanı seçimi, sayfalama ve hata biçimi. Web arayüzü, mobil uygulama ve CLI'nin yaptığı her şey bu API üzerinden gider.

API referansını açmak

  • Kullanıcı menüsü → API referansı (aç Spitfire'da: /api/docs): bütün endpoint'ler konu konu, her birinin hangi rolü istediği ve API token'ıyla çağrılıp çağrılamayacağı.
  • Makine okunur belge: https://<spitfire-adresiniz>/api/v1/openapi.json (OpenAPI 3.1, giriş gerektirmez). Postman, Insomnia ya da istemci kodu üreten araçlara bu adresi verin.

Referans sayfasında Try it out isteği sizin oturumunuzla gönderir: okuma güvenlidir, ama yazan bir istek (test silmek, koşu başlatmak) gerçekten yapılır.

Kimlik doğrulama

Her istek Authorization: Bearer <token> header'ıyla gider. İki tür token var:

Token Nereden Ne yapabilir
Oturum token'ı POST /api/v1/auth/login (iki adımlı doğrulama açıksa ardından POST /api/v1/auth/mfa); süresi kısa, POST /api/v1/auth/refresh ile yenilenir Kullanıcının rolünün izin verdiği her şey
API token'ı (sfpat_…) Kullanıcı menüsü → API token'ları (ayrıntı) Bütün okuma (GET) endpoint'leri (API token listesi ve yalnızca oturumla çalışan endpoint'ler hariç) ve yalnızca şu yazmalar: koşu başlatmak ve durdurmak, senaryo doğrulamak ve planlamak, karşılaştırmalı koşu başlatmak, durdurmak ve sürdürmek, PR yorum deposunu bağlamak, deploy bildirmek, planlı bakım

API token'ı sahibinin o anki rolü ve gruplarıyla çalışır. Token yönetimi, kullanıcı, ayar ve test düzenleme gibi işler oturum ister; token'la çağrılırsa 403 api_token_scope döner. Referansta her endpoint'in yanında x-spitfire-access (gereken rol: public, user, workspace-admin, installation-admin) ve x-spitfire-api-token (token'la çağrılabilir mi) yazar.

bash
curl -s -H "Authorization: Bearer $SPITFIRE_TOKEN" \
  "https://spitfire.example.com/api/v1/runs?status=failed&pageSize=10"

curl -s -X POST -H "Authorization: Bearer $SPITFIRE_TOKEN" -H "Content-Type: application/json" \
  -d '{"note": "nightly", "tags": ["ci"]}' \
  "https://spitfire.example.com/api/v1/tests/<test-id>/runs"

Çalışma alanı: İstekler kullanıcının o anki çalışma alanında çalışır. Başka bir alan için X-Spitfire-Workspace: <id ya da ad> header'ını (ya da ?workspace=) gönderin.

SCIM (/scim/v2) kendi token'ıyla çalışır ve SCIM biçiminde yanıt verir; kurulumu SCIM ile kullanıcı yönetimi bölümünde.

Yanıt ve hata biçimi

/api/v1 altındaki her JSON yanıt aynı zarfla gelir:

json
{ "success": true, "data": { }, "msg": "", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736" }

Hata olduğunda success false olur, error alanında değişmeyen bir code (bad_request, unauthorized, forbidden, api_token_scope, not_found, conflict, too_many_attempts, internal…), bir message, bazen details bulunur. 5xx hatalarında requestId de gelir: destekle yazışırken bunu verin. /api/v1 altında bilinmeyen bir adres de aynı zarfla 404 döner.

Raporlar (HTML/PDF), CSV dışa aktarmaları, canlı koşu akışı (server-sent events) ve paylaşılan bağlantılar zarf kullanmaz; referansta her birinin içerik türü yazar.

Sayfalama

Sayfalı listeler (testler, koşular, karşılaştırmalı koşular, denetim kaydı, sistem olayları) page (1'den başlar) ve pageSize (varsayılan 25, en çok 200) alır; zarfa total ve totalPages eklenir. Diğer listeler tek seferde gelir.

Sınırlar

Giriş, parola sıfırlama ve SSO endpoint'leri adres başına sınırlıdır (429 too_many_attempts). Request body JSON (UTF-8), aksi yazmıyorsa en çok 8 MB.