Router & routes

The Router (src/moxie/libraries/modules/router.js) is the source of truth for matching URLs and loading handlers. Route entries live in src/settings/routes/sites/*.js and src/settings/routes/shared.js.

Route entry (typical shape)

'content.spark': {
    routes: ['{type}', '{type}/{id}'],
    variables: {
        type: ['articles', 'images', 'sections', 'tags', 'videos']
    },
    group: 'content',
    specification: 'json-api',
    caching: 'standard'
}

Property	Purpose
routes	Path patterns after the site prefix; {token} segments are dynamic.
variables	Allowed values for a token; omitted tokens behave as wildcards.
group	Extra directory segment under src/apis/... (namespace).
specification	Response spec (e.g. json, json-api, mobile, xml) — see src/settings/specs/.
caching	Cache policy bucket — see src/settings/caching/.
framework	Fallback only when no endpoint index.js exists (often template).

Resolution order (critical)

For a matched route, the Router builds an API path and tries in order:

1. apis/{site-or-shared}/{group?}/{api-with-dots-as-slashes}/...
2. If the route defines a path variable (e.g. {version}), try .../{variable}/{value}/index.js first.
3. Fall back to base .../index.js.
4. Only if no index.js exists, load the route’s framework from frameworks/{framework}/index.js.

Implications:

• If an endpoint index.js exists, the route’s framework is ignored (Router may log a warning). The effective default is almost always the endpoint’s own index.js.
• Most routes explicitly set framework: 'template' as a safety net for template-only endpoints without a custom class.

Shared vs site handlers

• Site-specific routes use handlers under src/apis/foxnews/, foxbusiness/, etc.
• Shared routes use src/apis/shared/ for cross-brand endpoints (articles, videos, search, RSS patterns, etc.).

Adding a new endpoint (checklist)

1. Add or extend a route in the correct src/settings/routes/... file.
2. Create src/apis/.../your-endpoint/index.js exporting a handler with handle(route, config) (and optional parse).
3. Add config.js for querystring defaults and querystrings.options validation where needed.
4. For JSON:API style, add mapping.js and optional helpers/compute.js, helpers/querystrings.js.
5. For template output, add template.dot and config.sources in config.js.

See Frameworks & patterns for file contracts.