API'ye genel bakış

dashboard'ın ve alaf server CLI'sinin yapabildiği her şey aynı HTTP API'sine yapılan bir çağrıdır: proje oluşturma, deploy'ları tetikleme, domain'leri bağlama, analitik okuma, yedekleri yönetme. Bu, Hono üzerine kurulu düz bir JSON API'sidir, bu sayede bir script'ten, bir CI işinden veya bir AI agent'tan, birinci taraf istemcilerin yaptığı gibi yönetebilirsiniz.

Kimlik doğrulama

Bir istek, kimliğini tam olarak dört yoldan biriyle kanıtlar. Alaf Server önce bir Bearer token'ı, ardından bir oturum çerezini, sonra da loopback fallback'i (yalnızca bu mod etkinse) kontrol eder.

curl https://your-host/api/projects \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN"

İzinler

Kimlik doğrulandıktan sonra, her route bir izin kontrolü çalıştırır. Her route resource:action — project:read, domain:write, deployment:admin — şeklinde bir etiket bildirir ve alt kaynaklar araya bir segment ekler (project:service:write). Eylem, HTTP yöntemiyle uyumludur: read (bir tane GET), write (POST/PUT/PATCH), admin (DELETE ve yıkıcı), list (bir koleksiyon GET).

Erişim kuruluş başına belirlenir. Alaf Server, X-Organization-Id header'ından (oturum varsayılanınıza geri döner) hangi kuruluşu kastettiğinizi çözer, ardından oradaki rolünüzü kontrol eder — owner, admin, member veya restricted (yalnızca yetki). Herhangi bir route'un etiketi eksikse Alaf Server önyüklemeyi reddeder, bu nedenle yanlışlıkla korunmasız bir endpoint yoktur. Modül sayfalarındaki endpoint başına tablolar, her route için etiketi listeler; tam model için İzinler ve roller bölümüne bakın.

Hız limitleri

Tüm /api yüzeyi hız limitine tabidir. Kimliği doğrulanmamış istekler IP başına varsayılan bir limite tabi iken; kimliği doğrulanmış istekler kullanıcı başına daha cömert bir bütçe alır. Bazı route grupları daha sıkı veya daha gevşek adlandırılmış bir politika taşır. Limitler her dönen dakika içindir.

Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset header'larını taşır. /api/health asla sınırlanmaz (load balancers ve SSR onu sorgular).

Hata yapısı

Hatalar, kararlı bir yapıyla JSON olarak geri döner: insan tarafından okunabilir bir error mesajı ve, tipik hatalar için, makine tarafından okunabilir bir code. Doğrulama hataları, alan düzeyinde bir details haritası ekler.

{ "error": "This access token is read-only", "code": "TOKEN_READ_ONLY" }

Route grupları ve kullanılabilirlik

Route'lar modül başına monte edilir. Çoğu her deploy modunda mevcuttur; birkaçı yalnızca self-hosted'dir (ana bilgisayar dosya sistemine, SSH'ye veya yerel kuruluma dokunurlar ve bulut modunda asla yüklenmezler) ve bulut gateway'i route setini moda göre değiştirir.

Modül referansı