React

Server Actions vs an API route

Server Actions fit mutations a React form calls; an API route serves the outside world, with a stable, testable contract.

Key points

  • A Server Action is a function that runs on the server, called from a component: it has no public URL.
  • An API route has a contract, a method and a status: it serves webhooks, mobile apps and third parties.
  • Both need an explicit authorisation check: neither adds one on its own.

A Server Action is the right choice when the mutation starts inside a form in your component; an API route is right when the caller sits outside the application.

The difference that matters

A Server Action has no public address: Next exposes it as a generated endpoint and the client calls it through a reference. An API route has a path, a method and a status code, so it can be documented, versioned and called with curl.

The mutation, in its short form

// app/actions.ts
"use server";

export async function renameProject(id: string, name: string) {
  await db.project.update({ where: { id }, data: { name } });
  revalidatePath("/projects");
}

The "use server" directive marks the file; revalidatePath invalidates the page cache after the write. The component imports the function and passes it to a form action, with no fetch and no hand-built payload.

When you need a URL

  • Webhooks: an external service needs a stable address and a signature, not a generated reference.
  • Third-party clients: a mobile app or a script does not know the internal Next protocol.
  • Observability: a path with a method and a status is easier to trace in logs and end-to-end tests.

Build and start

npx next build
npx next start

Server Actions need a Node or edge runtime compatible with Next: on static hosting they do not exist, because no server runs them.

Live records in the catalogue

Three upload components, where the difference shows: use-image-upload, file-upload-card and file-upload. To browse by category start from 111,985 components.

The limitation

Server Actions are not safer for running on the server: a caller can invoke them with arbitrary arguments, so authorisation and validation go inside. They are also not cacheable like a GET, and they offer no natural way to answer a client that is not React.

Where to continue

The direct comparison is in route handlers vs Server Actions; input validation is in validating Server Actions; the boundary between the two environments is in server-only and client-only.

Frequently asked questions

Is a Server Action safer than an API route?

No. Both are reachable from the client, so authorisation and argument validation belong inside the function.

Can another service call a Server Action?

Not stably: the generated endpoint is not a public contract. An external service needs an API route.

Do Server Actions work on static hosting?

No, they need a server to run them. On a static site the mutation goes through an external API route or a dedicated service.

How do you handle errors in a Server Action?

Return an object with the state and the message instead of throwing: the exception reaches the client as a generic error in production.

Can I use them with React without Next.js?

Not stably yet: support depends on the bundler and the framework. Outside Next, an API route is the safer choice.