Choose a Server Route when appropriate and return correct HTTP responses for success and failure.
Start with who will call it
Prefer a Server Function when only the current Start app calls the operation and end-to-end types matter. Use a Server Route for webhooks, third-party clients, mobile apps, or a stable HTTP contract. Both run on the server, but they serve different callers.
Return complete HTTP semantics
A Server Route handler returns a Response directly. Set status 404 explicitly when a resource is absent instead of throwing the page-router notFound() helper. Choose no-store, private, or shared caching for successful data according to whether identity affects it.
import { createFileRoute } from '@tanstack/react-router'
import { findIssue } from '~/server/issues'
export const Route = createFileRoute('/api/issues/$issueId')({
server: {
handlers: {
GET: async ({ params }) => {
const issue = await findIssue(params.issueId)
if (!issue) {
return Response.json({ error: 'Issue not found' }, { status: 404 })
}
return Response.json(issue, {
headers: { 'Cache-Control': 'no-store' },
})
},
},
},
})Treat it as a real external boundary
Path params, search params, headers, and bodies all come from untrusted callers. Validate at runtime and enforce authentication, authorization, and rate limits before writes. Keep error bodies stable and never expose stacks, SQL, or internal file paths.
Turn this lesson into a verifiable skill
An external client can call the endpoint with standard HTTP and receive explicit status, headers, and body.
Add a GET `/api/issues/$issueId` endpoint with distinct success, invalid-parameter, and missing-resource responses.
Use curl to verify all three responses, including Content-Type, status code, and JSON shape.
- Implementing a public external API as a server-function RPC.
- Always returning 200 and hiding errors inside JSON fields.