For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /tr/docs/modules/api.md (or send Accept: text/markdown).

API modülü

Sürümlenmiş genel sözleşme, anahtar tesisatı ve OpenAPI yüzeyi.

Bu kılavuz hakkında sor

Başlamadan önce

İndirdiğiniz supastack projenizi Visual Studio Code'de Dosya → Klasörü Aç'ı kullanarak açın ve ardından Terminal → Yeni Terminal'i seçin. Depo kökü package.json'u, uygulamaları ve paketleri içeren klasördür. Aşağıdaki komutu orada çalıştırın ve terminalini açık bırakın. Bir komut tanınmazsa devam etmeden önce araç kurulum kılavuzunu tamamlayın.

Önce platform eğitimini okuyun. Sunucu, tarayıcı veya telefon isteklerini yanıtlayan uygulama işlemidir. Web, apps/web/.env.local'yi okur, Expo, apps/mobile/.env.local'yi okur ve veritabanı geçiş komutları root .env'yi okur. Veritabanı olmayan/gösterge paneli gösterimi, Postgres'nin taşınmasını gerektiren gerçek/auth hesaplarından ayrıdır. Yalnızca telefona veya masaüstüne yönelik bir ödeme, ayrı olarak çalışan bir Web arka ucuna ihtiyaç duyar.

corepack pnpm --filter @supastack/web dev

Kurulum ve yapılandırma

packages/api, genel REST yüzeyinin doğruluk kaynağıdır: istekler, yanıtlar ve hata zarfı için zod şemaları ile /api/v1/openapi'de sunulan OpenAPI belgesi (openApiDocument). Rota işleyicileri şekilleri yeniden tanımlamak yerine bu şemaları bir araya getirir.

API anahtarları çalışma alanı başına sk_<env>_ önekiyle düzenlenir, sabit zamanlı karşılaştırmayla karma saklanır ve kapsam taşır — varsayılan okuma. api-keys.ts oluşturma, arama ve iptali sahiplenir.

apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi

Uygulama iş akışı

Uç noktaları mevcut sürüm içine ekleyin: şemaları genişletin, hata zarfını koruyun ve /api/docs doğru kalsın diye OpenAPI yüzeyini yeniden üretin. Kırıcı değişiklikler sessiz şekil değişikliği değil, yeni sürüm alır.

Çağıranın çalışma alanını sunulan anahtardan çözün, web uygulamasıyla aynı yetkilendirme ve doğrulama kurallarını uygulayın ve anahtar başına hız sınırlayın.

Doğrulama ve sorun giderme

Her rota şeklini paket şemalarına karşı sözleşme testi yapın. Bilinmeyen anahtarların, iptal edilmiş anahtarların ve yetersiz kapsamlı isteklerin hepsinin belgelenen hata zarfıyla başarısız olduğunu ve OpenAPI belgesinin geçerli JSON kaldığını doğrulayın.