Endpoint mapping
Arc derives command and query routes from namespaces and names. A generated client calls the same URLs only when the server and proxy-generator route options stay aligned; changing the server convention alone does not update the client.
Start with the convention below for the Tasks artifacts. Change it for the whole application when you need a different prefix or namespace layout. If one public URL must survive a file move, pin that artifact’s route with @path instead.
The convention
Section titled “The convention”A route is the prefix, the namespace segments, and the name, each converted to kebab case:
- Start with
generatedApis.routePrefix,apiby default. An empty string removes the prefix. A prefix may contain letters, digits,_,-, and/between segments. - Split the namespace on dots and drop the first
generatedApis.segmentsToSkipForRoutesegments. - Convert each remaining segment and the name to kebab case. Acronyms stay together:
CreateTaskbecomescreate-task,HTTPReaderbecomeshttp-reader, and_becomes-.
For a model-bound artifact, the namespace comes from its folder below the discovery root, or from @command({ namespace }) and @readModel({ namespace }). The name is the command class name, or the query method name:
| Artifact | Namespace | Route |
|---|---|---|
RegisterTask in Features/Tasks/Registration/ |
Tasks.Registration |
POST /api/tasks/registration/register-task |
TaskItem.allTasks in Features/Tasks/Listing/ |
Tasks.Listing |
GET /api/tasks/listing/all-tasks |
A query’s identity still includes the read-model class, Tasks.Listing.TaskItem.allTasks, even though the route does not. Direct calls and generated clients use that identity.
Every command also gets a validation route: its route followed by /validate. A command whose own route ends in /validate, such as one named Validate, still executes on that route.
Change the convention
Section titled “Change the convention”To change the convention for all derived routes, pass generatedApis to ArcApplication.createBuilder(...) or new ArcServer(...). In this excerpt, segmentsToSkipForRoute: 1 drops the first namespace segment; the prefix and name-inclusion settings are shown explicitly:
const builder = ArcApplication.createBuilder({ generatedApis: { routePrefix: 'api', segmentsToSkipForRoute: 1, includeCommandNameInRoute: true, includeQueryNameInRoute: true }});| Option | Default | Effect |
|---|---|---|
routePrefix |
'api' |
First route segment; '' for none |
segmentsToSkipForRoute |
0 |
Leading namespace segments to drop, such as a company name |
includeCommandNameInRoute |
true |
Omit the command name when false, unless that would make two routes in one namespace collide |
includeQueryNameInRoute |
true |
The same for queries |
Keep the proxy generator route options in step with these, or generated clients call the wrong URL.
Pin one route with @path
Section titled “Pin one route with @path”A file move can change a discovery-derived route. If clients already depend on the URL, use an explicit path rather than making them follow the file move:
@command()@path('/api/tasks/register')export class RegisterTask { /* fields and handle() */ }The command above uses /api/tasks/register regardless of its discovery-derived namespace. @path works on a command or read-model class, and on a @query() method, where it overrides the class path. The path must start with a single /, contain only letters, digits, /, _, and -, and must not contain ... A trailing slash is removed, and the prefix is not added. Low-level definitions take path as a property instead.
@path on a static method without @query() fails at build: it would have no effect.
What startup rejects
Section titled “What startup rejects”The server refuses to start rather than serve a weakened contract when a name or namespace segment does not start with a letter or contains anything but letters, digits, and _ (even with an explicit path), when a path or prefix is unsafe, when two operations share a namespace and name (compared case-insensitively), or when two routes collide, including a command’s /validate route and the reserved /.cratis and /openapi.json paths. The full list is in Configuration.
Reserved paths
Section titled “Reserved paths”| Path | Purpose |
|---|---|
/.cratis/commands, /.cratis/queries |
Introspection |
/.cratis/identity-details/schema, /.cratis/me |
Identity |
/.cratis/users, /.cratis/tenants |
Development users and tenants |
/.cratis/queries/ws, /.cratis/queries/sse |
Multiplexed observable queries |
/.cratis/queries/health |
Query health, when enabled |
/openapi.json |
OpenAPI |
The complete route table, with methods and answers, is in the HTTP contract reference.