0Pricing
Vue Academy · Lesson

Nuxt Server Routes and API Endpoints

server/api/ directory, defineEventHandler(), H3 utilities, middleware, error handling.

Nuxt Server Routes and API Endpoints is a free Vue Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Vue Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Nuxt Is Full-Stack

Nuxt 3 includes a server engine (Nitro). The server/ directory lets you build API endpoints alongside your pages — no separate backend needed for many apps.

The server/api Directory

Files in server/api/ become API routes under /api. server/api/hello.ts responds at /api/hello.

server/
  api/
    hello.ts   ->  /api/hello
    posts.ts   ->  /api/posts

defineEventHandler

Every server route exports a handler created with defineEventHandler. Whatever it returns is sent as the response, serialized to JSON automatically.

// server/api/hello.ts
export default defineEventHandler((event) => {
  return { message: 'Hello from the server' }
})

HTTP Method Suffixes

Add a method suffix to the filename to restrict it. users.get.ts handles GET, users.post.ts handles POST. Without a suffix, the route answers any method.

server/api/
  users.get.ts   ->  GET /api/users
  users.post.ts  ->  POST /api/users

Reading Query Parameters

Use the getQuery helper to read the URL query string from the event.

export default defineEventHandler((event) => {
  const query = getQuery(event)
  return { search: query.q }
})

Reading the Request Body

For POST/PUT requests, readBody parses the incoming JSON body. It is async, so await it.

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return { received: body }
})

Dynamic Server Routes

Bracket filenames work on the server too. server/api/users/[id].get.ts reads the id with getRouterParam.

export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')
  return { id }
})

Throwing HTTP Errors

Use createError to return proper HTTP error responses with a status code and message instead of throwing a plain error.

export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id')
  if (!id) {
    throw createError({ statusCode: 400, statusMessage: 'Missing id' })
  }
})

The H3 Event Object

The event argument comes from H3, Nitro's HTTP framework. It carries the request and response and is the entry point for all the helper functions.

Setting Status and Headers

Helpers like setResponseStatus and setHeader let you control the response when returning a value is not enough.

export default defineEventHandler((event) => {
  setResponseStatus(event, 201)
  setHeader(event, 'Cache-Control', 'no-cache')
  return { created: true }
})

Calling Your API From Pages

From a page, fetch your own endpoint with useFetch or $fetch. During SSR Nuxt calls the handler directly, skipping an HTTP round-trip.

const { data } = await useFetch('/api/posts')

Quick Check

Test your knowledge of Nuxt server routes.

Recap

You learned Nuxt server routes:

  • Files in server/api/ become API endpoints.
  • defineEventHandler defines a handler; its return value is the response.
  • .get.ts/.post.ts suffixes scope the HTTP method.
  • Use getQuery, readBody, getRouterParam, and createError on the H3 event.

Frequently asked questions

Is the “Nuxt Server Routes and API Endpoints” lesson free?

Yes — the full text of “Nuxt Server Routes and API Endpoints” is free to read here on the web, and the Vue Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Vue Academy course, upgrade to CoddyKit PRO.

What will I learn in “Nuxt Server Routes and API Endpoints”?

server/api/ directory, defineEventHandler(), H3 utilities, middleware, error handling. You practise Vue Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Vue Academy?

No prior experience is required. Vue Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Nuxt Server Routes and API Endpoints” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Vue Academy lesson?

Yes. Every Vue Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Nuxt 3 Project Structure and File-Based Routing
  2. Data Fetching: useFetch and useAsyncData
  3. Nuxt Server Routes and API Endpoints
  4. SSR vs SSG vs SPA Mode
← Back to Vue Academy