[{"data":1,"prerenderedAt":187},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fmain\u002Fversioning":3},{"id":4,"title":5,"body":6,"description":174,"extension":175,"group":176,"meta":177,"navigation":178,"order":179,"path":180,"section":181,"seo":182,"source":183,"stem":184,"version":185,"__hash__":186},"docs\u002Fdocs\u002Fmain\u002Fversioning.md","HTTP API versions",{"type":7,"value":8,"toc":166},"minimark",[9,14,91,95,99,105,109,120,124,135,139,155,159,162],[10,11,13],"h2",{"id":12},"add-an-http-version","Add an HTTP version",[15,16,21],"pre",{"className":17,"code":18,"language":19,"meta":20,"style":20},"language-sh shiki shiki-themes light-plus light-plus dark-plus","gonex module version users --http v1 --policy preserve --dry-run\ngonex module version users --http v1\ngonex module version users --http v2\n","sh","",[22,23,24,59,75],"code",{"__ignoreMap":20},[25,26,29,33,37,40,43,47,50,53,56],"span",{"class":27,"line":28},"line",1,[25,30,32],{"class":31},"swoLU","gonex",[25,34,36],{"class":35},"sFD8J"," module",[25,38,39],{"class":35}," version",[25,41,42],{"class":35}," users",[25,44,46],{"class":45},"stxUP"," --http",[25,48,49],{"class":35}," v1",[25,51,52],{"class":45}," --policy",[25,54,55],{"class":35}," preserve",[25,57,58],{"class":45}," --dry-run\n",[25,60,62,64,66,68,70,72],{"class":27,"line":61},2,[25,63,32],{"class":31},[25,65,36],{"class":35},[25,67,39],{"class":35},[25,69,42],{"class":35},[25,71,46],{"class":45},[25,73,74],{"class":35}," v1\n",[25,76,78,80,82,84,86,88],{"class":27,"line":77},3,[25,79,32],{"class":31},[25,81,36],{"class":35},[25,83,39],{"class":35},[25,85,42],{"class":35},[25,87,46],{"class":45},[25,89,90],{"class":35}," v2\n",[10,92,94],{"id":93},"preserve-or-replace-legacy-routes","Preserve or replace legacy routes",[96,97,98],"p",{},"The default preserve policy retains existing handlers and URLs. Adapter sources are copied into independent http\u002Fv1 and http\u002Fv2 packages; generated registration calls them with one shared service instance. Handwritten handlers, service\u002Frepository\u002Fmodel files and prior version packages are untouched. Reruns fail without overwriting. Resolve an edited generated registry before retrying.",[96,100,101,104],{},[22,102,103],{},"--policy replace"," explicitly stops registering legacy routes, while retaining their source files. That choice persists when later versions are added. No command deletes v1. Deprecation and retirement are application decisions; announce retirement and remove old registrations only as an explicit breaking change.",[10,106,108],{"id":107},"choose-a-prefix","Choose a prefix",[96,110,111,112,115,116,119],{},"Default prefixes are \u002Fapi\u002Fv1, \u002Fapi\u002Fv2. Use ",[22,113,114],{},"--prefix \u002Fcustom\u002Fv1"," when generating, or ",[22,117,118],{},"http.WithVersion(registrar,\"v1\",prefix)"," when registering manually. Versions are positive major identifiers (v1, v2, ...), never v0 or arbitrary path fragments. Version registration changes the typed contract and runtime path together, adds an operation-ID suffix and refuses collisions.",[10,121,123],{"id":122},"export-independent-contracts","Export independent contracts",[96,125,126,127,130,131,134],{},"\u002Fopenapi.json describes legacy routes. \u002Fopenapi\u002Fv1.json and \u002Fopenapi\u002Fv2.json describe their respective effective paths and independent schemas; each document validates against OpenAPI 3.1. ",[22,128,129],{},"App.OpenAPIVersion(\"v1\")"," exports a registered document without listening and rejects unknown versions. All public documents are disabled together with DisableOpenAPI. CLI export defaults to the legacy document; select a version with ",[22,132,133],{},"gonex openapi generate --http-version v1 --out v1.json",".",[10,136,138],{"id":137},"start-with-a-versioned-module","Start with a versioned module",[96,140,141,142,145,146,149,150,134],{},"Create an initially versioned module with ",[22,143,144],{},"gonex create module catalog --http-version v1",". This profile starts directly with http\u002Fv1 and does not register legacy routes. Compare each released document using ",[22,147,148],{},"gonex openapi validate --file current.json --against baseline.json","; see ",[151,152,154],"a",{"href":153},"\u002Fdocs\u002Fmain\u002Fupgrades\u002F","compatibility policy",[10,156,158],{"id":157},"handle-custom-adapter-layouts","Handle custom adapter layouts",[96,160,161],{},"Version generation expects the Phase 4 adapter Register signature and generated HTTP registry hook. Custom adapter layouts\u002Fsignatures may require a manual registration change; conflicts must be resolved before generation. Copying a version does not infer a new business API: edit its schemas and handlers to define the intended compatibility boundary.",[163,164,165],"style",{},"html pre.shiki code .swoLU, html code.shiki .swoLU{--shiki-light:#795E26;--shiki-default:#795E26;--shiki-dark:#DCDCAA}html pre.shiki code .sFD8J, html code.shiki .sFD8J{--shiki-light:#A31515;--shiki-default:#A31515;--shiki-dark:#CE9178}html pre.shiki code .stxUP, html code.shiki .stxUP{--shiki-light:#0000FF;--shiki-default:#0000FF;--shiki-dark:#569CD6}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":20,"searchDepth":61,"depth":61,"links":167},[168,169,170,171,172,173],{"id":12,"depth":61,"text":13},{"id":93,"depth":61,"text":94},{"id":107,"depth":61,"text":108},{"id":122,"depth":61,"text":123},{"id":137,"depth":61,"text":138},{"id":157,"depth":61,"text":158},"Keep version-specific HTTP adapters and contracts separate while sharing business behavior in Gonex.","md","APPLICATION DESIGN",{},true,100,"\u002Fdocs\u002Fmain\u002Fversioning","build",{"title":5,"description":174},"versioning.md","docs\u002Fmain\u002Fversioning","main","XIYPczEejkcN5yIulIZSG2Rov2Vjl-8cG3B-z_6rTyc",1792521640482]