MoxieDOCS
INSPECTOR
moxie/cookbook-new-endpoint

Cookbook: add a new endpoint

End-to-end checklist for shipping a new URL under a site prefix (e.g. fn/).

1. Pick the surface

  • Site-specific → src/settings/routes/sites/{site}.js + src/apis/{site}/...
  • Shared across brands → src/settings/routes/shared.js + src/apis/shared/...
  • Variable path (e.g. versioned config) → plan {variable} segments and overrides early

2. Add the route entry

Minimal shape:

'my.feature': {
    routes: ['my-endpoint', 'my-endpoint/{id}'],
    variables: { id: [] }, // or omit for wildcard
    group: 'mygroup',      // apis/{site}/mygroup/...
    specification: 'json-api',
    caching: 'standard',
    framework: 'template'  // fallback only if no index.js
}
  • Align group with the directory you will create.
  • Dots in route keys often map to nested paths — follow existing site file conventions.

3. Create the handler tree

src/apis/foxnews/mygroup/my.feature/
├── index.js      # export { handle, parse? }
├── config.js     # querystrings.default + querystrings.options
├── mapping.js    # if JSON:API
└── helpers/
    ├── compute.js
    └── querystrings.js

index.js must export a single default/class with handle(route, config). Keep it thin.

4. Implement config.js

  • Set querystrings.default for optional params.
  • Declare querystrings.options with type: string, number, csv, boolean, rewrite.
  • Do not re-validate the same params manually in index.js if config.js already encodes the rules.

See Querystrings & config.js.

5. JSON:API shaping

  • Add mapping.js with map, pluck, rewrite, static, group, compute, parse as needed.
  • Put non-declarative transforms in helpers/compute.js only when necessary.

See JSON:API mapping guide.

6. Template / RSS path

  • If the response is XML/HTML from doT, ensure framework: 'template' is meaningful or provide index.js that delegates to the template framework.
  • Add template.dot and config.sources.

See Template & doT.

7. Local verification

yarn dev
# http://localhost:3001/fn/my-endpoint?debugga=route,config
  • Confirm route match, merged config, and upstream source (debugga=source).

8. Tests & lint

yarn test
yarn lint

Add Jest coverage for pure helpers and critical mapping edge cases when feasible.

9. Deploy path

  • Merge to develop for dev Lambda (see Git workflow).
  • release-v* → stage; GitHub Release → prod.
edit this page