Kontrak API (NEXT-19)
Versi boleh dibaca mesin: contracts/api-contract.json (schema_version 1).
Disahkan oleh ujian: pkg/gateway/api_contract_test.go (gerbang),
sdks/go/yabanin_test.go (pariti SDK). Perubahan bentuk memecahkan keserasian: naikkan
schema_version dan kemas kini setiap ujian pariti.
1. Sampul ralat
Sebarang respons JSON bukan 2xx adalah tepat {"error":{message,type,param?,code?}};
message dan type tidak kosong. Ralat SSE menggunakan sampul yang sama sebagai
peristiwa data, ditamatkan oleh data: [DONE].
2. Badan kejayaan / kebolehnulan
chat.completion: id/object/choices (tatasusunan tidak kosong), content ialah rentetan tidak kosong (tidak pernah null); token penggunaan ialah nombor.- Kos tidak diketahui = null/tidak hadir, TIDAK SEKALI-KALI 0 (0 bermaksud respons percuma/tempatan yang jujur). Disahkan terhadap kontrak gerbang; UI mengikut peraturan ini.
3. Penomboran halaman
{page>=1, page_size, total (from COUNT — honest), total_pages} pada semua
endpoint senarai pentadbir; jenis klien papan pemuka menetapkan bentuk ini.
4. Unit
Wang melalui API ialah nombor apungan dalam *_usd (cost_usd/cost_in_usd).
Mikro-USD ialah perwakilan lekapan lejar dalaman dan tidak sekali-kali merentasi
API. Token ialah nombor.
5. SSE
Ketulan membawa object=chat.completion.chunk; strim tamat dengan
literal data: [DONE], termasuk selepas ralat. Pembatalan klien
diteruskan ke huluan (cancel), dan penggunaan separa direkodkan seperti yang diperhatikan
(lihat ADR-0001 untuk tetingkap perakaunan).
6. Keluarga laluan pentadbir (pariti dasar / prompt / identiti)
Keluarga berskop organisasi yang ditambah sejak beta; setiap satu dikawal oleh
kebenaran organisasi (org:<perm> — root memintas) dan dibaca melalui stor
berskop organisasi (RLS), jadi id sumber rentas organisasi dalam laluan menjawab 404, tidak sekali-kali
data organisasi lain. Laluan yang belum dihubungkan (stor tidak dikonfigurasi) menjawab 503 —
laluan ditetapkan oleh inventori, pendawaian bergantung pada pelaksanaan.
Talian paip dasar (org:policies.manage — dasar ialah objek
keselamatan; sejarah versi tidak boleh diubah):
GET|POST /api/organizations/{id}/policies
GET|PUT|DELETE /api/organizations/{id}/policies/{policyId}
GET /api/organizations/{id}/policies/drift managed | drift | unmanaged
GET /api/organizations/{id}/policy-decisions ?page&page_size&verdict&mode&policy_id
Peraturan kontrak: badan membawa yaml (dokumen Policy ypp/v1) +
attachments (key_label, model_pattern, endpoint, priority);
setiap mutasi menambah versi tidak boleh diubah yang baharu dan menaikkan kunci versi
organisasi; satah pentadbir mengesahkan sintaks YAML sahaja (kompilasi penuh berlaku
di sisi gerbang semasa muat — nama pengesan yang tidak diketahui disimpan tanpa masalah dan gagal
secara kelihatan dalam log keputusan). Baris keputusan mendedahkan verdik
(allow|flag|mask|deny), mod (shadow|enforce), id/versi dasar dan
bukti yang dihash sahaja — kandungan yang dipetik tidak sekali-kali kekal (pengekalan 90 hari).
Studio prompt (org:policies.manage — prompt ialah input talian paip:
prompt penilai memutuskan verdik; partial digantikan ke dalam badan dasar dan badan prompt):
GET|POST /api/organizations/{id}/prompts
GET|PUT|DELETE /api/organizations/{id}/prompts/{promptId}
POST /api/organizations/{id}/prompts/{promptId}/labels bind {label, version}
GET|POST /api/organizations/{id}/partials
PUT|DELETE /api/organizations/{id}/partials/{partialName}
Peraturan kontrak: nama selamat-rujukan [A-Za-z0-9_.-]+, unik bagi setiap organisasi;
suntingan MENAMBAH versi tidak boleh diubah (pengikatan label ialah penunjuk yang boleh diubah);
badan boleh membawa pemegang tempat {{var}} / {{partials.name}} — pemaparan
berlaku pada laluan render/render-template, tidak sekali-kali memutasikan versi yang disimpan.
Kelayakan MCP (root untuk CRUD pentadbir; pengesahan ejen org pada
aliran gerbang):
PUT|GET|DELETE /api/organizations/{id}/mcp/servers/{name}/credential
POST /api/mcp/credentials/{server} agent key; headers submit/rotate
POST /api/mcp/auth/{server}/begin agent key; oauth consent URL
GET /api/mcp/auth/{server}/callback public (IdP redirect target)
Lihat §7 untuk kontrak paparan rahsia dan Gerbang MCP untuk semantik rantai pengesahan.
Peruntukan SCIM (org:members.manage untuk token; pengesahan bearer scim
untuk pelayan):
POST|GET /api/organizations/{id}/scim/tokens
DELETE /api/organizations/{id}/scim/tokens/{tokenID}
/scim/v2/ServiceProviderConfig | /scim/v2/Users[/{id}] | /scim/v2/Groups[/{id}]
7. Kontrak paparan rahsia
Rahsia mentah merentasi API tepat sekali, semasa penciptaan, dan hanya di tempat
aliran memerlukannya (token bearer SCIM, kunci ejen); segala yang disimpan
dibaca semula secara bertopeng: baris kelayakan mendedahkan secret_last4 + has_secret,
tidak sekali-kali teks biasa atau teks sifer. Rahsia semasa rehat ialah sampul enc:;
penulisan tanpa penyulit yang dikonfigurasi gagal — tiada sandaran senyap
kepada teks biasa.