Skip to main content

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.