HTTP Endpoint Haritasi

HTTP endpoint haritası ve sözleşmeler

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

P, gerçek projenizin api_prefix değeridir; R resource path'i, D data source path'i, E event channel path'idir. Aşağıdaki aileler özelliklerin etkinliğine göre üretilir. İki projenin aynı route prefix'ini sahiplenmesi doğru değildir.

Alan	HTTP / yol biçimi	Koşul / açıklama
Proje metadata	GET P/meta	Güvenlik/policy uygulanır
OpenAPI	GET P/_openapi.json	docs_enabled
Swagger/ReDoc	GET P/_docs, GET P/_redoc	docs_enabled
Key üretme/liste	POST, GET P/admin/api-keys	Bootstrap veya yetkili kalıcı principal
Key revoke	DELETE P/admin/api-keys/{key_id}	Yetkili principal
JWT üretme	POST P/admin/jwt	Yerel JWT üretimi etkinse
SQL/Mongo liste/create	GET, POST P/R	allowed_actions
SQL/Mongo item	GET, PATCH, PUT, DELETE P/R/{item_id}	allowed_actions, tenant/owner
Sayım	GET P/R/_count	List eylemi; SQL'de ayrıca count_enabled
SQL batch create	POST P/R/_batch	Create eylemi ve batch_enabled
SQL operation	Yapılandırılan method + P/<path>	Varsayılan yol rpc/<name>
Data source read	Tanımlanan method + P/D	Static/file/http sözleşmesi
JSON file write	POST P/D, PATCH/PUT/DELETE P/D/{item_id}	Açık write policy; dosya backend'i
Custom endpoint	Tanımlanan method + P/<path>	Python handler/dependency/response config
Event publish	POST P/E	Publish izni
SSE	GET P/E/stream	SSE açık ve subscribe izni
WebSocket	WS P/E/ws	WS açık, query/subprotocol auth policy
Media upload	POST P/media	Medya etkin, multipart file
Media batch	POST P/media/_batch	Multipart files; öğe bazlı sonuç
Media bytes	GET P/media/{media_id}	Read/owner veya geçerli signed token
Media metadata	GET P/media/{media_id}/meta	İzinli metadata
Signed URL	POST P/media/{media_id}/signed-url	İmzalama anahtarı/policy
Media delete	DELETE P/media/{media_id}	Delete/owner ve metadata tutarlılığı

webhook_docs, OpenAPI webhook tanımı üretir; tabloda yeni bir webhook teslimatı veya alıcı endpoint'i varsayılmamalıdır. Global health/readiness/metrics yolları gözlemlenebilirlik; yönetim/ekip yolları control-plane referansındadır.

Uygulamanızın kesin listesini alın

forge routes
forge openapi --output forge-openapi.json

CLI seçeneğinin kendi sürümünüzle eşleştiğini forge openapi --help ile kontrol edin. HTTP OpenAPI alternatif olarak P/_openapi.json üzerinden alınabilir. Root docs ile proje docs farklı kapsam taşıyabilir.

İstek/yanıt kuralları

• Kimlik doğrulama, veri erişim izni ve input schema farklı kontrollerdir; yalnız schema doğrulanması işlemi yetkili yapmaz.
• PUT ile PATCH birbirinin takma adı değildir; CRUD sözleşmesini izleyin.
• Liste yanıtından total varsaymayın; sayım ayrı yol olabilir. Cursor modunda offset yardımcılarını kullanmayın.
• RPC'deki transaction ve idempotency, bütün CRUD/HTTP hook'larını otomatik kapsamaz.
• HTTP hatasının status/body/request-id değerlerini birlikte kaydedin. detail metnini programın kalıcı tek sözleşmesi haline getirmeyin.
• X-Request-ID, X-Forge-Cache, X-Forge-Idempotent-Replay gibi yanıt başlıkları teşhis ve tekrar bilgisidir; erişim yetkisi değildir. Gözlenen gerçek header adları için ilgili feature kodunu esas alın.
• SDK helper'ları standart /api/<project>/v1 convention'ını izler. Özel prefix ve HTTP method için düşük seviyeli request kullanın.

HTTP hata aileleri

Status	İncelenecek konu
400	Geçersiz sorgu/cursor veya iş girdisi
401	Eksik/geçersiz/sona ermiş credential
403	Yetki veya policy kapsamı
404	Kaynak yok, görünür değil veya route etkin değil
409	Idempotency fingerprint, revision veya transaction çatışması
413	İstek/dosya/yanıt sınırına ilişkin sunucu kontrolü
422	FastAPI/Pydantic/JSON schema input doğrulaması
429	Rate limit / kontrollü bekletme
503	Readiness, aşırı yük veya bağımlılık sorunu

Bu sınıflama her handler'ın bütün olası status'larının kapalı listesi değildir. Gerçek uygulama OpenAPI'si, özel Python kodu ve sorun giderme rehberi birlikte değerlendirilir.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• main/framework/routers/project.py
• main/framework/factory.py
• main/framework/cli.py
• main/docs/32-API-Semantics-and-HTTP-Contracts.md

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım