Next.js Server Actions vs API Routes: When to Use Each

# nextjs# serveractions# apiroutes# performance

Mahdi BEN RHOUMA

Understand the differences between Server Actions and API Routes in Next.js 15. Learn when to use each approach with real-world examples and performance comparisons.

Next.js Server Actions vs API Routes: When to Use Each

Next.js 15 gives you two ways to handle server-side logic: Server Actions and API Routes. Both work, but they're designed for different use cases. Choosing the wrong one leads to unnecessary complexity or missing features.

This guide teaches you when to use each approach.

Understanding the Differences

Server Actions

Server Actions are async functions that run on the server and are called directly from components.

// app/actions.ts
'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string

  const { data, error } = await supabase
    .from('posts')
    .insert({ title, content, user_id: userId })

  if (error) throw error
  return data
}

```typescriptrevert th
// app/posts/new/page.tsx
'use client'

import { createPost } from '@/app/actions'

export default function NewPostPage() {
async function handleSubmit(formData: FormData) {
const post = await createPost(formData)
console.log('Post created:', post)
}

return (

Create Post

)
}




### API Routes

API Routes are HTTP endpoints that handle requests and responses.



```typescript
// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  const { title, content } = await request.json()

  const { data, error } = await supabase
    .from('posts')
    .insert({ title, content, user_id: userId })

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 400 })
  }

  return NextResponse.json(data)
}

// app/posts/new/page.tsx
'use client'

export default function NewPostPage() {
  async function handleSubmit(formData: FormData) {
    const response = await fetch('/api/posts', {
      method: 'POST',
      body: JSON.stringify({
        title: formData.get('title'),
        content: formData.get('content')
      })
    })

    const post = await response.json()
    console.log('Post created:', post)
  }

  return (
    <form onSubmit={(e) => {
      e.preventDefault()
      handleSubmit(new FormData(e.currentTarget))
    }}>
      <input name="title" placeholder="Title" required />
      <textarea name="content" placeholder="Content" required />
      <button type="submit">Create Post</button>
    </form>
  )
}

Key Differences

Feature	Server Actions	API Routes
Call Method	Direct function call	HTTP request
CSRF Protection	Built-in	Manual
Type Safety	Excellent	Manual
Caching	Next.js cache functions	Manual
External Calls	Not possible	Possible
Middleware	No	Yes
Complexity	Simple	More verbose
Flexibility	Limited	High

When to Use Server Actions

Use Server Actions for:

Form Submissions

// ✅ Perfect for form submissions
'use server'

export async function updateProfile(formData: FormData) {
  const name = formData.get('name') as string
  const email = formData.get('email') as string

  const { error } = await supabase
    .from('profiles')
    .update({ name, email })
    .eq('id', userId)

  if (error) throw error
  revalidatePath('/profile')
}

Simple Mutations

// ✅ Good for simple mutations
'use server'

export async function deletePost(postId: string) {
  const { error } = await supabase
    .from('posts')
    .delete()
    .eq('id', postId)

  if (error) throw error
  revalidatePath('/posts')
}

Keeping Secrets Secure

// ✅ API keys stay on server
'use server'

export async function sendEmail(email: string) {
  // STRIPE_SECRET_KEY never exposed to client
  const response = await fetch('https://api.stripe.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STRIPE_SECRET_KEY}`
    }
  })

  return response.json()
}

Database Operations

// ✅ Direct database access
'use server'

export async function getPostsWithComments() {
  const { data } = await supabase
    .from('posts')
    .select(`
      *,
      comments(*)
    `)

  return data
}

When to Use API Routes

Use API Routes for:

Webhooks

// ✅ External services need HTTP endpoints
export async function POST(request: NextRequest) {
  const event = await request.json()

  if (event.type === 'charge.succeeded') {
    // Handle Stripe webhook
    await supabase
      .from('payments')
      .insert({ stripe_id: event.data.id, status: 'completed' })
  }

  return NextResponse.json({ received: true })
}

External Integrations

// ✅ Third-party services call your API
export async function POST(request: NextRequest) {
  const { apiKey } = request.headers

  // Verify API key
  if (apiKey !== process.env.EXTERNAL_API_KEY) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const data = await request.json()
  // Process data
  return NextResponse.json({ success: true })
}

Complex Business Logic

// ✅ Complex logic benefits from middleware and error handling
export async function POST(request: NextRequest) {
  try {
    const { userId, amount } = await request.json()

    // Validate
    if (amount < 0) {
      return NextResponse.json({ error: 'Invalid amount' }, { status: 400 })
    }

    // Check user balance
    const { data: user } = await supabase
      .from('users')
      .select('balance')
      .eq('id', userId)
      .single()

    if (user.balance < amount) {
      return NextResponse.json({ error: 'Insufficient balance' }, { status: 400 })
    }

    // Process transaction
    const { data: transaction } = await supabase
      .from('transactions')
      .insert({ user_id: userId, amount })

    return NextResponse.json(transaction)
  } catch (error) {
    return NextResponse.json({ error: 'Server error' }, { status: 500 })
  }
}

Rate Limiting

// ✅ Middleware for rate limiting
import { Ratelimit } from '@upstash/ratelimit'

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '1 h')
})

export async function POST(request: NextRequest) {
  const ip = request.headers.get('x-forwarded-for') || 'unknown'
  const { success } = await ratelimit.limit(ip)

  if (!success) {
    return NextResponse.json({ error: 'Rate limited' }, { status: 429 })
  }

  // Handle request
}

RESTful APIs

// ✅ Full REST API with multiple methods
export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const id = searchParams.get('id')

  const { data } = await supabase
    .from('posts')
    .select('*')
    .eq('id', id)
    .single()

  return NextResponse.json(data)
}

export async function POST(request: NextRequest) {
  const body = await request.json()
  const { data } = await supabase.from('posts').insert(body)
  return NextResponse.json(data)
}

export async function PUT(request: NextRequest) {
  const { id, ...updates } = await request.json()
  const { data } = await supabase
    .from('posts')
    .update(updates)
    .eq('id', id)
  return NextResponse.json(data)
}

export async function DELETE(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const id = searchParams.get('id')
  const { data } = await supabase.from('posts').delete().eq('id', id)
  return NextResponse.json(data)
}

Real-World Decision Tree

Is it a form submission or simple mutation?
├─ YES → Use Server Actions
└─ NO → Continue

Does an external service need to call your app?
├─ YES → Use API Routes
└─ NO → Continue

Do you need middleware or rate limiting?
├─ YES → Use API Routes
└─ NO → Continue

Do you need fine-grained HTTP control?
├─ YES → Use API Routes
└─ NO → Use Server Actions

Performance Comparison

Server Actions:

Lower latency (no HTTP overhead)
Direct function call
Automatic serialization
Built-in CSRF protection

API Routes:

Slightly higher latency (HTTP overhead)
More flexible
Manual serialization
Manual CSRF protection

For most applications, the performance difference is negligible (less than 10ms). Choose based on functionality, not performance.

Error Handling

Server Actions

'use client'

async function handleSubmit(formData: FormData) {
  try {
    const result = await createPost(formData)
    console.log('Success:', result)
  } catch (error) {
    console.error('Error:', error.message)
  }
}

API Routes

'use client'

async function handleSubmit(formData: FormData) {
  try {
    const response = await fetch('/api/posts', {
      method: 'POST',
      body: JSON.stringify(Object.fromEntries(formData))
    })

    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.message)
    }

    const result = await response.json()
    console.log('Success:', result)
  } catch (error) {
    console.error('Error:', error.message)
  }
}

Best Practices

Server Actions:

✅ Use for form submissions
✅ Keep them simple and focused
✅ Use revalidatePath for cache invalidation
✅ Throw errors for error handling
✅ Use FormData for file uploads

API Routes:

✅ Use for webhooks and external integrations
✅ Implement proper error handling
✅ Add rate limiting for public endpoints
✅ Validate all input
✅ Return appropriate HTTP status codes

Conclusion

Server Actions and API Routes both have their place. Use Server Actions for simple mutations and form submissions—they're simpler and have better type safety. Use API Routes for webhooks, external integrations, and complex business logic.

The key is understanding the trade-offs. Server Actions are simpler but less flexible. API Routes are more complex but more powerful. Choose the right tool for the job.

Originally published at https://iloveblogs.blog

Next.js Server Actions vs API Routes: When to Use Each

Next.js Server Actions vs API Routes: When to Use Each

Understanding the Differences

Server Actions

Key Differences

When to Use Server Actions

Form Submissions

Simple Mutations

Keeping Secrets Secure

Database Operations

When to Use API Routes

Webhooks

External Integrations

Complex Business Logic

Rate Limiting

RESTful APIs

Real-World Decision Tree

Performance Comparison

Error Handling

Server Actions

API Routes

Best Practices

Related Articles

Conclusion