HTTP Routes & Handler Boundaries

When this skill applies

Use this skill when a VTEX IO service needs to expose explicit HTTP endpoints through

service.json

routes and implement the corresponding handlers under

node/

Building callback or webhook endpoints
Exposing integration endpoints for partners or backoffice flows
Structuring route handlers and middleware chains
Validating params, query strings, headers, or request bodies
Standardizing response shape and status code behavior

Do not use this skill for:

sizing or tuning the service runtime
deciding app policies in
```
manifest.json
```
designing GraphQL APIs
modeling async event or worker flows

Decision rules

Use HTTP routes when the integration needs explicit URL contracts, webhooks, or callback-style request-response behavior.
In VTEX IO,
```
service.json
```
declares route IDs, paths, and exposure such as
```
public
```
, while the Node entrypoint wires those route IDs to handlers exported from
```
node/routes
```
. Middlewares are composed in code, not declared directly in
```
service.json
```
.
Keep route handlers small and explicit. Route code should validate input, call domain or integration services, and shape the response.
Put cross-cutting concerns such as validation, request normalization, or shared auth checks into middlewares instead of duplicating them across handlers.
Define route params, query expectations, and body shape as close as possible to the handler boundary.
Use consistent status codes and response structures for similar route families.
For webhook or callback endpoints, follow the caller's documented expectations for status codes and error bodies, and keep responses small and deterministic to avoid ambiguous retries.
Emit structured logs or metrics for critical routes so failures, latency, and integration health can be diagnosed without changing the handler contract.
Prefer explicit route files grouped by bounded domain such as
```
routes/orders.ts
```
or
```
routes/catalog.ts
```
.
Treat public routes as explicit external contracts. Do not expand a route to public use without reviewing validation, auth expectations, and response safety.

Hard constraints

Constraint: Route handlers must keep the HTTP contract explicit

Each route handler MUST make the request and response contract understandable at the handler boundary. Do not hide required params, body fields, or status code decisions deep inside unrelated services.

Why this matters

HTTP integrations depend on predictable contracts. When validation and response shaping are implicit or scattered, partner integrations become fragile and errors become harder to diagnose.

Detection

If the handler delegates immediately without validating required params, query values, headers, or request body shape, STOP and make the contract explicit before proceeding.

Correct

typescript

export async function getOrder(ctx: Context, next: () => Promise<void>) {
  const { id } = ctx.vtex.route.params

  if (!id) {
    ctx.status = 400
    ctx.body = { message: 'Missing route param: id' }
    return
  }

  const order = await ctx.clients.partnerApi.getOrder(id)
  ctx.status = 200
  ctx.body = order
  await next()
}

Wrong

typescript

export async function getOrder(ctx: Context) {
  ctx.body = await handleOrder(ctx)
}

Constraint: Shared route concerns must live in middlewares, not repeated in every handler

Repeated concerns such as validation, request normalization, or common auth checks SHOULD be implemented as middlewares and composed through the route chain.

Why this matters

Duplicating the same checks in many handlers creates drift and inconsistent route behavior. Middleware keeps the HTTP surface easier to review and evolve.

Detection

If multiple handlers repeat the same body validation, header checks, or context preparation, STOP and extract a middleware before adding more duplication.

Correct

typescript

export async function validateSignature(ctx: Context, next: () => Promise<void>) {
  const signature = ctx.request.header['x-signature']

  if (!signature) {
    ctx.status = 401
    ctx.body = { message: 'Missing signature' }
    return
  }

  await next()
}

Wrong

typescript

export async function routeA(ctx: Context) {
  if (!ctx.request.header['x-signature']) {
    ctx.status = 401
    return
  }
}

export async function routeB(ctx: Context) {
  if (!ctx.request.header['x-signature']) {
    ctx.status = 401
    return
  }
}

Constraint: HTTP routes should not absorb async or batch work that belongs in events or workers

Routes MUST keep request-response latency bounded. If a route triggers expensive, retry-prone, or batch-oriented work, move that work to an async flow and keep the route as a thin trigger or acknowledgment boundary.

Why this matters

Long-running HTTP handlers create poor integration behavior, timeout risk, and operational instability. VTEX IO services should separate immediate route contracts from background processing.

Detection

If a route performs large loops, batch imports, heavy retries, or work that is not required to complete before responding, STOP and redesign the flow around async processing.

Correct

typescript

export async function triggerImport(ctx: Context) {
  await ctx.clients.importApi.enqueueImport(ctx.request.body)
  ctx.status = 202
  ctx.body = { accepted: true }
}

Wrong

typescript

export async function triggerImport(ctx: Context) {
  for (const item of ctx.request.body.items) {
    await ctx.clients.importApi.importItem(item)
  }

  ctx.status = 200
}

Preferred pattern

Recommended file layout:

text

node/
├── routes/
│   ├── index.ts
│   ├── orders.ts
│   └── webhooks.ts
└── middlewares/
    ├── validateBody.ts
    └── validateSignature.ts

Wiring routes in VTEX IO services:

In VTEX IO,

service.json

declares route IDs and paths, the Node entrypoint registers a

routes

object in

new Service(...)

, and

node/routes/index.ts

maps each route ID to the final handler. Middlewares are composed in code, not declared directly in

service.json

json

{
  "routes": {
    "orders-get": {
      "path": "/_v/orders/:id",
      "public": false
    },
    "reviews-create": {
      "path": "/_v/reviews",
      "public": false
    }
  }
}

typescript

// node/index.ts
import type { ClientsConfig, RecorderState, ServiceContext } from '@vtex/api'
import { Service } from '@vtex/api'
import { Clients } from './clients'
import routes from './routes'

const clients: ClientsConfig<Clients> = {
  implementation: Clients,
  options: {
    default: {
      retries: 2,
      timeout: 800,
    },
  },
}

declare global {
  type Context = ServiceContext<Clients, RecorderState>
}

export default new Service<Clients, RecorderState>({
  clients,
  routes,
})

Minimal route pattern:

typescript

// node/routes/index.ts
import type { RouteHandler } from '@vtex/api'
import { createReview } from './reviews'
import { getOrder } from './orders'

const routes: Record<string, RouteHandler> = {
  'orders-get': getOrder,
  'reviews-create': createReview,
}

export default routes

typescript

// node/routes/orders.ts
import { compose } from 'koa-compose'
import { validateSignature } from '../middlewares/validateSignature'

async function rawGetOrder(ctx: Context, next: () => Promise<void>) {
  const { id } = ctx.vtex.route.params

  if (!id) {
    ctx.status = 400
    ctx.body = { message: 'Missing route param: id' }
    return
  }

  const order = await ctx.clients.partnerApi.getOrder(id)
  ctx.status = 200
  ctx.body = order

  await next()
}

export const getOrder = compose([validateSignature, rawGetOrder])

typescript

export async function createReview(ctx: Context, next: () => Promise<void>) {
  const body = ctx.request.body

  if (!body?.productId) {
    ctx.status = 400
    ctx.body = { message: 'Missing productId' }
    return
  }

  const review = await ctx.clients.reviewApi.createReview(body)
  ctx.status = 201
  ctx.body = review
  await next()
}

Keep domain logic in services or integrations, and keep route handlers responsible for HTTP concerns such as validation, status codes, headers, and response shape.

Common failure modes

Hiding request validation inside unrelated services instead of making route expectations explicit.
Repeating the same auth or normalization logic in many handlers instead of using middleware.
Letting HTTP handlers perform long-running async or batch work.
Returning inconsistent status codes or response shapes for similar endpoints.
Expanding a route to public exposure without reviewing its trust boundary.

Review checklist

Is HTTP the right exposure mechanism for this contract?
Are required params, headers, query values, and body fields validated at the route boundary?
Are repeated concerns factored into middlewares?
Does the handler stay small and focused on HTTP concerns?
Should any part of the work move to async events or workers instead?

Related skills

```
vtex-io-events-and-workers
```
- Use when expensive or retry-prone work should move out of HTTP handlers into async flows
```
vtex-io-auth-and-policies
```
- Use when deciding which policies or access rules should protect HTTP routes

Reference

Service - Route declaration and service exposure
Node Builder - Backend file layout and route implementation context
Using Node Clients - Client usage from route handlers

vtex-io-http-routes

NPX Install

Tags

SKILL.md Content

HTTP Routes & Handler Boundaries

When this skill applies

Decision rules

Hard constraints

Constraint: Route handlers must keep the HTTP contract explicit

Constraint: Shared route concerns must live in middlewares, not repeated in every handler

Constraint: HTTP routes should not absorb async or batch work that belongs in events or workers

Preferred pattern

Common failure modes

Review checklist

Related skills

Reference