ek9_add_route

Inserts the web operation (`byId() as GET for :/{id}` or `operator += for :/`) with a compiling stub body into the service; answers status, edits[] and summary, a duplicate route as conflicts[] (route-collision).

Category: Editor · Compare: Add Endpoint / Generate REST Method

When to use it

'Add GET /{id} to OrdersService' is one call with symbol:'OrdersService', name:'byId', uri:'/{id}' and parameters:[{name:'id', in:'PATH'}] - no file or line.

When not to use it

Target is a class, trait, or component (a normal method, not a web operation) - use ek9_add_method.
The service does not exist yet - create it with ek9_new_construct (service mode) first, then add routes here.
You want a value-type operator (==, <=>, ?, …) on a class/record, not an operator-form HTTP route - use ek9_add_operator.

Details

Renders via the SAME operation spec + renderer as ek9_new_construct service mode (ServiceOperationParser + ConstructScaffolder.renderServiceOperation), so a route added here is byte-identical to one created with the service. ONE route per call: an obvious duplicate (same operator or same named handler) is a conflicts kind 'route-collision', but this is not a full overload analyser — pre-check with ek9_query_effective_api. An unbound PATH var, unresolved param type, or unresolved 'constrain by' gate surfaces as would-fail; a non-service target is an error naming its actual genus.

Arguments

Argument	Type	Required	What it is
`file`	string		The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.
`name`	string		Named-route handler name (camelCase), e.g. 'byId'. Provide this OR 'operator'.
`operator`	string		Operator form of the route: += (POST), -= (DELETE), :^: (PUT), :~: (PATCH), ? (HEAD). Provide this OR 'name'.
`parameters`	array of object		Operation parameters: [{name, type, in:PATH\|QUERY\|HEADER\|CONTENT\|REQUEST\|CONTEXT, source?, sanitized?}] - each ONE object (this list's items carry 'in', so the bare 'name as Type' form does not apply); 'type' defaults to String when omitted. PATH/QUERY/HEADER are auto-captured into the response and referenced in content() so they compile.
`response`	object		Response customisations: {status?, contentType?, contentLanguage?, cacheControl? \| cache:{maxAge, visibility:public\|private, mustRevalidate?, noStore?}}. Only set fields are overridden; HTTPResponse defaults the rest.
`security`	string		Per-operation security posture ('open' or 'constrain by <Gate>'). Omit to inherit the service posture.
`symbol`	string	yes	The service the route is added to - a bare name ('OrdersService') finds its file workspace-wide; 'mod::OrdersService' when the name is declared in two modules.
`uri`	string		Operation path, e.g. '/{id}' or '/'. Path variables must be bound by a PATH param of the same name.
`verb`	string: GET \| POST \| PUT \| DELETE \| PATCH \| HEAD \| OPTIONS		HTTP verb for the named form. Default GET. Ignored for the operator form.

It also takes the arguments every tool takes.